tablesorter/README.markdown

tablesorter is a jQuery plugin for turning a standard HTML table with THEAD and TBODY tags into a sortable table without page refreshes. tablesorter can successfully parse and sort many types of data including linked data in a cell.

Documentation

• See the full documentation.
• All of the original document pages have been included.
• Information from my blog post on undocumented options and lots of new demos have also been included.
• Change log moved from included text file into the wiki documentation.

Demos

• Basic alpha-numeric sort Demo.
• Links to demo pages can be found within the main documentation.
• More demos & playgrounds - updated in the wiki pages.

Features

• Multi-column sorting.
• Multi-tbody sorting - see the options table on the main document page.
• Parsers for sorting text, alphanumeric text, URIs, integers, currency, floats, IP addresses, dates (ISO, long and short formats) & time. Add your own easily.
• Support for ROWSPAN and COLSPAN on TH elements.
• Support secondary "hidden" sorting (e.g., maintain alphabetical sort when sorting on other criteria).
• Extensibility via widget system.
• Cross-browser: IE 6.0+, FF 2+, Safari 2.0+, Opera 9.0+.
• Small code size.
• Works with jQuery 1.2.6+

Licensing

• Copyright (c) 2007 Christian Bach.
• Original examples and docs at: http://tablesorter.com.
• Dual licensed under the MIT and GPL licenses.

Change Log

View the complete listing here.

Version 2.2 (5/3/2012)

• Multiple tbody sorting:
  • Each tbody within a table will now sort separately.
  • To add in a non-sorting tbody, add the class "tablesorter-infoOnly", modifiable by the new cssInfoBlock option
  • See the main document's options table for an example.
  • NOTE The pager plugin will only be applied to the first tbody as always. I may work on modifying this behavior in the future, if I can figure out the best implementation.
• Added ignoreCase option:
  • When true (default), text character case is ignored during sorting.
  • If false, upper case characters will sort before lower case characters.
• Added textSorter option:
  • This option allows using a custom text sorter (e.g. naturalSort.js).
  • Suggestion by alisonatwork in issue #58.
  • New demo added.
• Modified sortLocaleCompare option:

  • This option no longer switches the sort to use the String.localeCompare method.

  • When this option is true, the text parsed from table cells will convert accented characters to their equivalent to allow the alphanumeric sort to properly sort.

  • If false (default), any accented characters are treated as their value in the standard unicode order.

  • The following characters are replaced for both upper and lower case (information obtained from sugar.js sorting equivalents table):

    • áàâãä replaced with a
    • ç replaced with c
    • éèêë replaced with e
    • íìİîï replaced with i
    • óòôõö replaced with o
    • úùûü replaced with u
    • ß replaced with S

  • If you would like to continuing using the String.localeCompare method, then set the sortLocaleCompare option to false and use the new textSorter option as follows:

    $('table').tablesorter({
      textSorter: function(a,b) {
       return a.localeCompare(b);
      }
    });
    

Version 2.1.20 (4/28/2012)

• Optimized table rebuilding after sort by using a document fragment instead of appending cells directly to the table. This results in about a 20% increase in sort speed (very roughly determined).
• Optimized pager table rebuilding to also use document fragments, and by removing two extra calls that reapplied the current widgets.

Version 2.1.19 (4/23/2012)

• The filter widget will now ignore leading spaces so when the filter_startsWith is true it will match the text. Fix from issue #55. Thanks to aarkay18 for the code!
• Fixed a problem with empty table cells returning an empty string instead of parsing the cell - needed when there is HTML like an input tag to process. Reverted the change accidently added back in version 2.1.15.
• Added a resort flag that when set to false, it will prevent the resorting of the table when "update", "updateCell" or "addRows" is called. Use the appropriate format below:
  • update: `$('table').trigger('update', [false]);
  • updateCell: $('table').trigger('updateCell', [ this, false ]); - see the updating a table cell demo.
  • addRows: $('table').trigger('addRows', [$row, false]); - see the adding table rows demo.

Version 2.1.18 (4/23/2012)

• When the sticky headers widget is applied to a table with multiple header rows, adding the class name sticky-false to any header row will prevent it from becoming sticky. Thanks to megatom for the suggestion in issue #52!
• Updated filter widget css to better work with twitter's bootstrap. Fix per issue #54. Thanks thezoggy!
• Modified the green theme arrows; see the columns style widget demo and choose the green theme to see the change. I've included the PSD files as well.

Version 2.1.17 (4/21/2012)

• Fixed an error reported in issue #52 which occurrs when using the metadata plugin after the last update.
• The sticky headers widget will now work properly if TD's are included in the header, but the following should be noted:
  • The selectorHeaders option needs to be changed to thead th, thead td to properly include the TD's.
  • CSS changes to the blue theme were needed and most likely any custom themes to add a background color to these cells.
  • To prevent the TD's from being sortable, add a sorter-false class name to it.
• Updated the blue theme:
  • TD's in the sticky header should now have a background color applied.
  • Replaced the black arrow background image gifs with data uri. Included comments with white arrow data uri.
• Updated filter widget to more accurately count the number of columns. There was an issue with multiple header rows.

Version 2.1.16 (4/20/2012)

• Removed emptyToBottom option. It has been replaced with the emptyTo option.

• Added emptyTo option:

  • Setting it to top will always sort all empty table cells to the top of the table.
  • bottom will always sort all empty cells to the bottom of the table.
  • none or zero will treat empty cells as if their value was zero.
  • Individual columns can be modified by adding the following, set in order of priority:
    • metadata class="{ empty: 'top' }". This requires the metadata plugin.
    • headers option headers : { 0 : { empty : 'top' } }.
    • header class name class="empty-top".
    • Overall emptyTo option.
  • Updated the sorting empty cells demo.
  • Fix for issue #48.

• Add stringTo option in version 2.1.16. This options sets the string value for all of the numerical columns.

• Modified the string option which is only applied to text within a numerical column; setting the value to:

  • max will treat any text in that column as a value greater than the max (more positive) value. Same as the max+ value, which was retained for backwards compatibility.
  • min will treat any text in that column as a value greater than the min (more negative) value. Same as the max- value.
  • top will always sort the text to the top of the column.
  • bottom will always sort the text to the bottom of the column.
  • none or zero will treat the text as if it has a value of zero.
  • Individual columns can be modified by adding the following, set in order of priority:
    • metadata class="{ string: 'top' }". This requires the metadata plugin.
    • headers option headers : { 0 : { string : 'top' } }.
    • header class name class="string-top".
    • Overall stringTo option.
  • Updated the text strings in numerical sort.
  • Fix for issue #50.

• Fixed sticky header widget to now include multiple rows. Fix for issue #52.

Version 2.1.15 (4/18/2012)

• Modified the emptyToBottom option:
  • Clarified that setting this option to null will treat empty cells as if they had a value of zero. Fix for issue #48.
  • Modified the script so that empty cells do not call their respective parser to keep the emptyAtBottom functionality working properly. Fix for issue #49.

Version 2.1.14 (4/17/2012)

• Updated "shortDate" parser to include the time, if provided. I've also updated the Changing the date format demo with a few times.

Version 2.1.13 (4/17/2012)

• Modified "digit" parser to not remove alphabetical characters as it was breaking the text strings in numerical sort functionality.