tablesorter/README.md

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 alphanumeric 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+ (jQuery 1.4.1+ needed with some widgets).
• Works with jQuery 1.9+ ($.browser.msie was removed; needed in the original version).

Licensing

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

Special Thanks

• Big shout-out to Nick Craver for getting rid of the eval() function that was previously needed for multi-column sorting.
• Big thanks to thezoggy for helping with code, themes and providing valuable feedback.
• Big thanks to ThsSin- for taking over for a while and also providing valuable feedback.
• And, of course thanks to everyone else that has contributed, and continues to contribute to this forked project!

Change Log

View the complete listing here.

Version 2.14.1 (11/22/2013)

• Filter widget
  • External inputs bound using the filter bindSearch function now clear on the "filterReset" event.
  • Replace Array.indexOf() due to IE8.
• Pager (plugin & widget)
  • Replace Array.indexOf() due to IE8. Fixes issue #388.
• Themes
  • Non-sortables headers now show the default cursor
  • Fix Dropbox theme to work properly within the sticky header demo
  • Fix Ice theme to include a top border in the sticky header demo
  • Tweaked sticky header widget to better align columns in Firefox & adjust caption to hide border edges.
  • See the sticky header demo to see these changes.
  • Fixes #407.
• Documentation
  • Update FAQ page to include information on the zebra widget not always working.
  • Update demos to use Bootstrap 3.0.2.
  • Add search instructions to the wiki documentation pages.
  • Add link to FAQ & search instructions on the main documenation page.
• Add associated core version number to pager addon & widget, main widget file and filter formatter file.

Version 2.14.0 (11/19/2013)

Core

• Changed sorting algorithms:
  • Due to problems with sorting multiple columns improperly sorting algorithms again include code to sort empty cells.
  • Internal sorting again has separate ascending and descending functions; but the previous $.tablesorter.sortNatural (ascending only), $.tablesorter.sortNumeric (ascending only) and $.tablesorter.sortText (ascending only) functions are still available.
  • Custom text & numeric sort functions, added via textSorter and numberSorter options now require you to return the sort in the correct direction.
  • Custom sort functions no longer have empty cells automatically handled for you.
  • Fixes issue #419.
• Added sortStable option which when true will sort exactly equal items by placing them in their original unsorted order (or, perform a stable sort).
• Removed double icon class names.
• Added tabIndex option
  • When true, a tabindex is added to the headers for keyboard accessibility; this was previously always applied
  • When false, table headers will not be included when tabbing through the page
  • Fulfills issue #415.

Filter widget

• Setting a filter to build a select no longer causes an error. Fixes issue #421.
• Added filter_saveFilters option
  • When true, this option saves the current filters using the storage utility (local storage with cookie fallback).
  • This option is set to false by default.
  • See issue #388.
• Allow multiple external filter inputs
  • The $.tablesorter.filter.bindSearch( $table, $external ) function now allows binding searches using the built-in functioning.
  • The bind search function will unbind any previously bound keyup and search event listeners on the $external elements.
  • External inputs must not have a tablesorter-filter class to distinguish them from internal filters.
  • If not using the filter_anyMatch option, external filters can be set to target specific columns by including a data-column attribute.
  • See the new filter external inputs demo.
• Filter reset button clicks will again trigger a filterReset event. Fixes issue #423.

Grouping widget

• Merged in fix for grouping widget + filter widget + child row widget.
  • Updated demo with multi-child column styling.
  • Thanks Xamamule in pull #414!
  • This also fixes issue #422.
• Renamed variables & cleanup
• Added group_dateString function to format the date string for group-date header class name.

Zebra widget

• Now skips removable rows added by other widgets, more specifically, it skips rows with a remove-me class name (set by the selectorRemove option).

Docs updates

• Added a side menu with search to the main document page.
  • The main documentation page now uses Bootstrap for some styles.
  • Search includes a count with clear search, previous result and next result buttons.
  • Search options included to find letters or whole words only, and choose if the search is case sensitive, or not.
  • The advantage of this search over the browser's built-in search (Ctrl-F) is that this search will find text within the hidden content
  • Indexing of the search results may not always be in order, i.e. "10/10" may not always be the lowest result on the page due to nested elements.
  • Sorry, IE7 and older users, the search works but but is really slow. And the side menu styling leaves much to be desired (using Bootstrap).
• jQuery UI theme selector updates. See issue #407.
• Updated typos & css in various demos
• Added Utility options section for options used by parsers, storage utility and pager ajax data.
• Added removed options section.
  • This applies to pager options available in the original version of tablesorter which are no longer supported.
  • Fixes issue #416.
• Added kbd styling for better visualization of keyboard keys.

Other

• Renamed variables within the pager custom control demo (still in beta)
• Renamed variables within default widgets file
  • Utilities: storage, addHeaderResizeEvent,, resizableReset
  • Widgets: columns, resizable, stickyHeaders, uitheme, saveSort
• Updated parser-date-two-digit-year.js to allow changing the date range
  • Set a different date range by adding a value to table.config.dateRange.
  • Instructions added to main documents under utility options
• Storage utility ($.tablesorter.storage) now accepts a jQuery object as well as a DOM object of the table
  • $.tablesorter.storage( $('#mytable'), 'myvariable', 'YAY' );, or
  • $.tablesorter.storage( $('#mytable')[0], 'myvariable', 'YAY' );

Version 2.13.3 (11/9/2013)

• Pager (plugin/widget)

  • Fixed initial filter settings when using pager ajax. Fixes issue #388.
  • Fixed ajax pager not recognizing column sorting. Fixes issue #408.
  • The core plugin now remove rows from table when using pager ajax. Fixes issue #411.

• Filter widget

  • Renamed all variables & restructured the entire widget.
  • Added better integration with the pager plugin/widget to minimize ajax server calls by getting default filter settings. Fixes issue #388.
  • Fixed filter formatter HTML5 spinner to properly find exact matches.
  • Added a new fuzzy search parameter
    • Fuzzy searches match sequential characters, similar to how Sublime Text searches work
    • Start the search with a tilde ~ followed by any sequential characters to match.
    • Examples: ~bee will match both "Bruce Lee" and "Brenda Lee", ~bcd will find "Brandon Clark" and ~piano will find "Philip Aaron Wong"
  • Added filter_anyMatch
    • Set this option to true when using an external search filter.
    • Setting this option should work properly with or without the column filters. The only issue you would have is if you triggered a search on the table using an array with undefined or null array values.
    • Some limitations are applied when using any match. Search operators, range queries and not-matches are not allowed.
    • See the demo for examples & more details.
    • Thanks to @prainho for the suggestion, code and feedback in issue #405!
  • Modified the bindSearch function to allow using it on external filters:
    • Use as follows: $.tablesorter.filter.bindSearch( $('table'), $('.search') );
    • Binding the search input using this method allows the search to use filter_liveSearch, delayed searching and pressing escape to clear the search.
    • See the filter any match demo for example usage.

• UITheme widget

  • Added caption styling
  • Updated css for jQuery UI theme and Bootstrap theme.

• Theme, demo & doc updates

  • Added jQuery UI theme switcher to jQuery UI theme demo & jQuery UI filter formatter demo.
  • Added ignore articles parser to saveSort widget demo.
  • Updated history of changes made to cssAsc, cssDesc & cssHeader on the main documentation page. See issue #407.

Version 2.13.2 (11/2/2013)

• Updated pager & filter widget to work when the pager countChildRows option is true:
  • Filter widget now properly added a "filtered" class to child rows
  • Pager plugin & widget now properly calculate a correct total number of rows
  • See issue #396.
• Updated editable widget to target table cell children if they exist
  • This fixes the issue in IE where making a table element contenteditable is not allowed.
  • See issue #404 for further details.

Version 2.13.1 (10/31/2013)

• Fixed filter widget issues
  • filter indexing will now be correct, even if a "tablesorter-filter" input/select doesn't exist in the filter row
  • Already parsed filters (filter-formatter) will not attempt to reparse the value; problem was caused by parsed dates.

Version 2.13 (10/30/2013)

• Added a "Development" branch to the repository.

  • I have started development on version 3 of tablesorter and this branch will have a basic structure to allow modularization of tablesorter.
  • So far, only the tablesorter core has been restructured and reorganized.
  • Added basic Zepto support to the core and some basic widgets, this is a work-in-progress. See issue #398.

• Ensure resized headers have stored data, or provide a fallback. Fixes issue #394.

• Added pager countChildRows option (plugin & widget)

  • When true, the pager treats child rows as if it were a parent row and strictly enforces showing only the set number of pager rows.
  • This can cause problems as a child row may not appear associated with its parent, may be split across pages or possibly distort the table layout if the parent or child row contain row or cell spans.
  • When false the pager always includes the child row with its parent, ignoring the set pager size.
  • See issue #396.

• Removed triggered change event to fix issue #400.

• Merged in filter formatter fix for jQuery UI dateFormat conflict; pull #403. Thanks @Craga89!

• Grouping widget update

  • Added group_separator option which is used when a group-separator-# class name is applied
  • Updated grouping widget demo.

• Added a file-type parser

  • Optimally used with the grouping widget to sort similar file types (e.g. video extensions: .mp4, .avi, .mov, etc)
  • File type sorting demo added.

• Updated LESS theme to work properly with LESS 4.1+

• Other changes

  • Improved formatFloat() replace method.
  • Sorting a zero hex value (0x00) is now possible.