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.4 (5/20/2012)

• Added selector change suggested by AnthonyM1229 in issue #74 to fix IE8 ignoring class name parsers. Thanks again Anthony for all of your hard work and input!

Version 2.3.3 (5/19/2012)

• Fixed the method used to get data from jQuery data, meta data, header options or header class names.
  • This should fix the "filter-false" problem reported in issue #73,
  • and fix issue #74 with setting parsers by class name.
• Performance improvements:
  • Modified the zebra and columns widget to use document fragments to modify changes to the table. I didn't log all of the times, but there was a speed increase in reported time when using the triggered events demo (1022 rows).
  • Changed the shortDate parser to cache header information.
• Updated multiple demos to show how to set some options using jQuery data, class names, etc.
  • Date format.
  • Lock sort order.
  • Initial sort order.
  • Set parser by class name.
  • Disable filter widget. NOTE: this widget uses the getData() function that doesn't exist in the original tablesorter.

Version 2.3.2 (5/11/2012)

• Added a method to remove tablesorter from a table
  • Use $('table').trigger('destroy'); to remove it.
  • Some classes applied by widgets will remain (zebra, columns, etc); but the functionality will be removed. I've been thinking about adding a "remove" function to each widget to specifically remove that widget.
  • Rows hidden by the filter widget will not reappear. I may work on an option to fix that in the future.
  • The "tablesorter" class is removed from the table; but if you want to leave this class, then use this example: $('table').trigger('destroy', [false]);.
• Fixed percent parser to not be automatically applied to text columns. Fix for issue #67.
• Fixed filter widget not working in v2.3.1. It was actually a problem with getting jQuery data breaking the widget.
• The first tbody can now be an info block.
  • Change suggested by kristerkari in pull request #68.
  • Updated multiple tbodies demo.
• The zebra and column widgets should now properly ignore info blocks (it was missing periods in the class selectors!).
• Text extracted from table cells is now automatically trimmed of extra spaces, tabs and carriage returns. If these elements are important to you, then please refer to the advanced use custom parser demo which allows you to access the table cell $(cell) directly.
• Fixed and/or updated a bunch of demos:
  • Demos that include jQuery UI seem to need jQuery v1.4+ now or script errors will completely break the plugin. Updated ui theme and sticky headers widget demos.
  • Render headers demo now targets the div wrapping header cell contents. Previously it was a span.

Version 2.3.1 (5/8/2012)

• Fixed an issue where header & metadata settings would ignore sorter:false inappropriately.
• Fixed minified version:
  • Apparently Dean Edwards packer now breaks the minified version, so I switched to using Uglify.
  • I prefer Google Closure Complier but it completely removes the eval needed to get multi-column sorting to work unless the "Whitespace only" mode is used and results in a file 2k larger than the Uglify version.
• Modified header settings to now check for settings with the following priority: jQuery data > metadata > headers option > header class name > overall option. Added:
  • dateFormat
  • lockedOrder - no demo.
  • sortInitialOrder
  • filter widget - no demo.
• Added the ability to set the sortList via jQuery data. See the updated sortList documents on how to use it
• Fixed date parsers (isoDate, usLongDate, shortDate and time) which did not handle empty cell data properly.

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.