Dec 2013 : description of the sortTable javascript library.   Modified Jan 2021
 
 *** March 2021 : this is mostly deprecated (it has problems with jQuery 3.x). We recommend using wsurvey_sortTable.js instead!  ***


 Requirements:

     This requires the jQuery library, and the wsurveyUtils1 library

 Usage:

    In an "onLoad" function (or document.ready()), initialize a table (or several tables) that you wish to make sortable.
    This is done using the setupSortTable function.

    setupSortTable adds arrow buttons to the top row (the column header row) of the selected table. When clicked, these buttons will
    call the sortTable function. sortTable will sort rows,  and display the results.

    The simplest setup does not require you to explicitily call sortTable-- setupSortTable will create the proper buttons & events.
    However, you can specify a custom function to use on button click, a function  that will call sortTable and perhaps other functions.
    This can be useful, say to appropriately color alternating rows in the sorted table. Examples of this usage are given below.


 What does this do?

  The table will be replaced with a sorted version, retaining the attributes/formatting of the original rows and cells.
  Note that if alternating colors were used in the original table, the colors are moved with the content -- the colors
  probably won't be alternating any more (you can use the colorRowsTable function, described below, as a workaround)

  Each cell can contain any html. However, sorting will occur on two possible values:
     The first non-whitespace text element.
     If there is an element, anywhere in the table cell, with a   "_sortUse" attribute, the value of this _sortUse attribute is used.
   The "_sortUse" trick allows the sorting to be independent of what is displayed.

   Thus:
     <td>3</td>
     <td> <span _sortUse="3" />33</td>
     <td> 3 <a href="go3">more</a>
  will all sort using  a value of "3"

  By default, a "natural" sort is used.
  However, you can specify numeric, alphabetical, or case-insensitive alphabetical.
  To specify a sort, include a "_sortType="stype" ' attribute in the header (top) row of a column of the table --
  that column will use the specified stype.
  Valid (case insensitive) stypes are:
     A  : alphabetical
     I  : case insensitive alphabetical
     N  : numeric

  By default, the first row is ALWAYS assumed to be headers, and will NOT be sorted. You can modify this behavior by using the
  'col,row' syntax in the column argument of setupSortTable.
  If you do this, odd things can happen (i.e.; if you sort on row 0, the header row is moved)

  If a row does NOT have the same number of columns as the first row, it is skipped ... and will cause problems.
  So this function basically assumes same number of columns per row


Description of setupSortTable

  istat=setupSortTable(tableid,ascKey,descKey,sortFunc,notDo,arrowBr,,startRow)

      Add click-to-sort arrows to the cells in the top row of a table; that will call sortTable (or custom sortFunc that then calls sortTable)

      tableid: id of the table (as a string), or dom node or jQuery object, of the table.
      ascKey : the Up arrow (ascending sort). Default is &uarr;   (&uarr; used if ascKey=0)
      descKey: The down arrow (descending sort). Default is &darr;  (&darr used if descKey=0)
      sortFunc: Name of a function to call instead of sortTable (a string).
                Note: use a string name, not an unquoted function name.
                I.e.; setupSortTable('mytable',0,0,'mySorter')
                For example: mySorter could call sortTable, and then calls colorRowsTable
                If 0, use sortTable
      notdo: If specified, a csv of columns to NOT place sort graphics on. i.e' notDo='1,3' means columns 1 and 3 will NOT have the
             clickable arrows. Numbering starts at 1 (not at 0).
             Special values: if a value <0 (say, -1 or -3), then not only does the column not have sort arrows, it won't even be sorted!
             That is, the orignal order is stored, the table sorted, and then these values are reinserted.
             This is a way of having a column of row numbers that won't change.
             0 means ignore
      arrowBr: If specified and equal 1, then put a <br> before the up and down arrows (so they are in a different row in the header). This can
               be a useful way of conserving horizontal space.
               0 means ignore
     externalHeader: If specified, the id of an element (such as a div). The header row of the table will be copied there --
                  this can be used to create "fixed headers"  that do not move (so that scrolling the table will not effect the
                   visiblity of this external-headers display.
                  If not specified, or '', then the "header row" will not be created.
     startRow : row to start sorting AFTER. This row, and rows above this, are not sorted. By default, 1 (i.e.; do NOT sort header row)

      -------------------
Other functions:
      -------------------

  istat=colorRowsTable(tableid,colTop,col2,...)

    Color the rows of a table (using a bgcolor in the <tr>).
      tableid: name, or dom node or jQuery object, of the table
      colTop : color of the first row. ie.; colTop='blue', or colTop='#abcdab'
      col1,col2,..: a list of colors. Row colors will cycle through these colors. Typically, 2 is enough!

    istat= returns the rows in the table (not including top row)

    Note: colorRowsTable(tableid) will return the rows in the table and do nothing else

      -------------------


    stat=sortTable(tableid,column,desc,nosorts)

  where
        tableid: either a string containing the ID of the table (ie; "foo1" in <table id="foo1 ...>), a DOM object, or a jQuery object
                 pointing to the table (say jid=$('#foo1');

        column: the column to sort on. The first column is 1 (NOT 0).
                If column > # of columns in the table, nothing will happen
           or
          'column,row'  :  the column to sort on, and the row to start with. If row not specified, start with row 2 (row 1, the top row, assumed to be headers)
           or
           'column,row,aid'  : if aid, then the header row is copied to a the aid element (as a 1 row table), and then is hidden.
        desc : if 1, sort in descending order
        nosorts: csv of columns to NOT sort   == with numbering starting at 1 (not at 0)

        If column is not specified, column 1 is sorted.
        If desc is not specified, sort is in ascending order

  stat : 0 if failure, other name of column; or nameOfColumn_desc if descending sort

   =====================

Example:
  <script type="text/javascript" src="jquery-1.10.2.js"></script>
  <script type="text/javascript" src="sortTable.js"></script>
  <script type="text/javascript" src="wsurveyUtils1.js"></script>

  <body onLoad="setupSortTable('test1',0,0,'doit1');doit1('test1');" >

  where the direct call to doit1 just "colors the rows" ...

  function doit1(a1,a2,a3,a4) {
     if (arguments.length>1) goo=sortTable(a1,a2,a3,a4) ;   // don't sort table onLoad
     colorRowsTable(a1,'cyan','lime','#effeef');       // after sorting (or onLoad), alternate row colors
     return 0;
   }