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: 3 33 3 more 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 ↑ (↑ used if ascKey=0) descKey: The down arrow (descending sort). Default is ↓ (&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
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 ). 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 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; }