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.3 (5/8/2012)

• Added ability to sort all columns under a header cell that spans multiple columns.
  • Previously clicking on the header cell would only sort the left-most column.
  • Added a demo.
• Added support for "Content-type: application/xhtml+xml". Fix for issue #62. Thanks to MelTraX for the fix!
• Added delayInit option:
  • This option delays parsing of all table cell data until the user initializes a sort.
  • This speeds up the initialization process of very large tables, but the data still needs to be parsed, so the delay is still present upon initial sort.
  • Enhancement suggested by MelTraX in issue #66.
• Column parsers & settings can now be set using jQuery data.
  • This setting has a higher priority than metadata: jQuery data > metadata > headers option > header class name > overall setting.
  • This applies to the parsers, stringTo and emptyTo options.
• Nested tables will no longer be targeted inappropriately. Fix for issue #65. Thanks to MelTraX for sharing some code!
• Reordered parsers to detect other numeric parsers before the general one. Fix for issue #64.
• Completed minor document corrections, general code cleanup, optimization and removal of a global variable.

Version 2.2.2 (5/4/2012)

• Sorting algorithm replaced with naturalSort.js. Suggestion by alisonatwork in issue #58.
• Non-sorting tbodies with "tablesorter-infoOnly" class name should no longer sort internal rows.
• Added a multiple tbodies sorting demo.

Version 2.2.1 (5/4/2012)

• Widgets should now apply properly while the pager is active. Fix for issue #60.

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.