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.12 (10/18/2013)

Core

• Added numberSorter option allowing you to modify the overall numeric sorter.

• Updated the textSorter option to allow setting a text sorter for each column.

  • The textSorter functon parameters have changed from (a, b, table, column) to (a, b, direction, column, table).
  • Restructured & combined sorting functions internally so that tablesorter will always sort empty cells no matter what sorting algorithm is used by the textSorter.
  • Renamed $.tablesorter.sortText() to $.tablesorter.sortNatural()
  • Added a new basic alphabetical sort algorithm $.tablesorter.sortText = function(a, b) { return a > b ? 1 : (a < b ? -1 : 0); }; which can be set using the textSorter option.
  • New examples can be found in the updated custom sort demo.

• Added fixedUrl option for use with the $.tablesorter.storage() function.

  • Setting this with a fixed name (it doesn't need to be a url) allows saving table data (saveSort widget, savePages in pager widget) for tables on multiple pages in a domain.
  • Additional storage options are described below under "Storage".

• An accurate number of table columns is now contained within table.config.columns. This accounts for multiple header rows, tds, ths, etc.

• Replaced .innerHTML with jQuery's .html() to fix issues in IE8. Fixes issue #385.

• Version numbers should now all be accurate, even in the comments.. at least this time ;). Fixes issue #386.

Pager

• In attempts to initialize the pager after the filter widget:
  • Added a pager widget (still beta testing) to allow initializing the pager after certain widgets (filter widget).
  • Updated tablesorter core (properly count table columns) & filter widget code to allow it to initialize on an empty table (thanks @stanislavprokopov!).
  • Hopefully one or both of these changes fixes issue #388.
  • New pager widget demos: basic & ajax.
• savePages option
  • Should no longer cause an error if stored data is malformed or unrecognized. Fixes issue #387.
  • The stored size and page is now cleared if the table is destroyed.
• Fixed an error occuring in IE when trying to determine if a variable is an array (toString function call not recognized). Fixes issue #390.
• Updated pager rendering to prevent multiple ajax calls.
• During this update, the pager page size would return as zero and set the totalPages value to inifinity. Yeah, it doesn't do that anymore; but you can still set the pager size to zero if you want!

Widgets

• Filter widget:
  • Should now properly initialize when the pager plugin/widget is used with ajax and/or the filter_serversideFiltering option is true. Fixes issue #388.
  • Please note that the select dropdowns still sort using the natural sort algorithm, but since it is using the function directly, empty cells will not sort based on the emptyTo option. If this is a big problem, let me know!
• Grouping widget:
  • Added group_callback option - this sets a callback function which allows modification of each group header label - like adding a subtotal for each group, or something. See the updated demo.
  • Added group_complete option which is "groupingComplete" by default. This is the name of the event that is triggered once the grouping widget has completed updating.
• Updated the editable widget:
  • Added editable_editComplete option which names the event that is triggered after tablesorter has completed updating the recent edit.
  • You can also bind to the change event for that editable element, but it may occur before tablesorter has updated its internal data cache.
• Storage
  • The $.tablesorter.storage() function now has options including the fixedUrl option described in the core section above.
  • Also added storage options which can be used for custom widgets: $.tablesorter.storage(table, key, value, { url : 'mydomain', id : 'table-group' }).
  • Additionally, for already build-in widgets, you can apply data-attributes to the table: <table class="tablesorter" data-table-page="mydomain" data-table-group="financial">...</table>.
  • For more details, please see issue #389.

Parsers

• Added an IPv6 parser
  • This parser will auto-detect (the is function checks for valid IPv6 addresses).
  • Added a new IPv6 parser demo.
  • Included rather extensive unit tests for just this parser o.O.

Version 2.11.1 (10/11/2013)

• Fixed an updating bug:
  • The pager was not updating properly
  • The updateComplete event was not firing when not using ajax.
  • Thanks @sbine for sharing the fix!

Version 2.11 (10/10/2013)

Core

• Initialized widgets (widgets with options) are now tracked to ensure widget options are extended when using "applyWidgets". Fixes issue #330.
• An javascript error no longer pops up when setting the delayInit option to true and using the saveSort widget (or triggering a sorton method). Fixes issue #346.
• Only visible columns will be considered when fixing column widths. Fixes issue #371.
• Merged in fix for jQuery version check (pull #338). This also fixes issue #379. Thanks @lemoinem!
• Removed natural sort's ability to sort dates. This shouldn't be a problem since tablesorter uses parsers detect & parse date columns automatically. Fixes issue #373.
• Fixed issue #381.
  • Any class name that is set by an option and is later used to search for that element now has an empty default class name.
  • The reasoning is that if a developer adds two class names to the option, the jQuery find breaks.
  • All default single class name options are now contained within $.tablesorter.css
  • Options affected include: tableClass, cssAsc, cssDesc, cssHeader, cssIcon, cssHeaderRow, cssProcessing in the core.
  • Note that the cssIcon option retains it's default class name & functionality to not add an <i> inside the table cell if this extra class name is undefined.
  • Widget options affected include: filter_cssFilter and stickyHeaders.
• Removed return false from header mouse/keyboard interaction. Fixes issue #305 & issue #366.

Parsers

• Fixed sugar date parser demo to point to the correct parser file and sugarjs resource.
• General cleaned up date, fraction and metric parsers & fixing of minor bugs.

Build Table Widget (new)

• Build a table starting with an assortment of data types ( array, text (CSV, HTML) or object (json) ).
• This widget isn't really a widget because it is run and does it's processing before tablesorter has initialized; but the options for it are contained within the tablesorter widgetOptions.

Column Widget

• General cleanup

Filter Widget

• Exact matches can still be made if the user enters an exact match indicator twice (i.e. John== will still find John in the column; before it would think the user was looking for John= after the second = was typed)
• Dynamically added filter reset buttons will now work automatically. Added by pull #327. Thanks @riker09!
• Chrome appears to have fixed the hidden input bug, so reverted changes to the basic filter demo. Fixes issue #341.
• The filter widget will work properly with sub-tables. Fixes issue #354. Thanks @johngrogg!
• Fixed issues with filter_columnFilters set to false. Fixes issue #355.
• Searches now have accents replaced if the sortLocaleCompare option is true. Fixes issue #357.
• Merged in enhancement for the filter widget & updated docs - add row to filter_functions parameters (issue #367, pull #368). Thanks @gknights!
• FilterFormatter jQuery UI Datepicker now includes the user selected time for comparisons. Thanks @TheSin-!
• Another fix to the filteFormatter jQuery UI Datepicker to make it work properly with the sticky header widget. Thanks @TheSin-!
• Removed filter_cssFilter default class name. The "tablesorter-filter" class name is automatically added, and this option now contains any additional class names to add. Fixes issue #381.

Grouping Widget

• The grouping widget now works across multiple tbodies.
• Added group-false header option which disables the grouping widget for a specific column. Fixes issue #344.
• Added the group_collapsed option which when true and the group_collapsible option is also true, all groups will start collapsed. Fulfills issue #352.
• You can now toggle all group rows by holding down the shift key while clicking on a group header.
• This widget now works properly with the pager addon (pager addon updated). Fixes issue #281.

StickyHeaders Widget

• Caption outerheight now used to get the correct full height of the caption. Thanks @TheSin-!
• stickyHeaders_zIndex option added to allow users to customize their sticky header z-index. Fixes issue #332. Thanks @TheSin-!

UITheme widget

• Updated Bootstrap theme to work with Bootstrap v3
  • Only additions were made to the sorting icons class names within in the $.tablesorter.themes.bootstrap defaults (contained in the jquery.tablesorter.widgets.js file).
  • So the theme will support all current versions of Bootstrap, just make sure you are using the appropriate icon class name (icon-{name} = v2; glyphicon glyphicon-{name} = v3).
  • Removed the gradient background from the header & footer cells.
  • Added a reduced icon font side for header sort icons.
  • Renamed the pager class from pager to ts-pager as Bootstrap adds a lot of padding to that class. See Bootstrap theme demo.
  • Thanks @YeaYeah for sharing how to fix the top border in issue #365.

Pager

• Fixed the removeRows option error when set to true.
• The pager now stores any object returned by the ajaxProcessing function in table.config.pager.ajaxData
  • The object should contain attributes for total (numeric), headers (array) and rows (array of arrays).
  • A replacement output option can also be loaded via this method and must be included in the output attribute (i.e. ajaxData.output).
  • Additional attributes are also available to the output display by using the attribute key wrapped in curly brackets (e.g. {extra} from ajaxData.extra).
  • Additional attributes can also be objects or arrays and can be accessed via the output string as {extra:0} (for arrays) or {extra:key} for objects.
  • The page number is processed first, so it would be possible to use this string {extra:{page}} ({page} is a one-based index), or if you need a different value use {page+1} (zero-based index plus any number), or {page-1} (zero-based index minus any number).
  • For more details, please see issue #326.
  • Thanks @camallen for the suggestions & feedback!
• The "updateComplete" event should now properly trigger after an ansynchronous ajax call has completed. Fixes issue #343.
• Added a new savePages option
  • Requires requires the $.tablesorter.storage script within the jquery.tablesorter.widget.js file to work properly.
  • When true, it saves pager page & size if the storage script is loaded (requires $.tablesorter.storage in jquery.tablesorter.widgets.js).
  • The pager will continue to function properly without the storage script, it just won't save the current page or pager size.
  • Fulfills enhancement request from issue #345.
• Removed table update when using ajax with a server that is already doing all of the work. Fixes issue #372 & issue #361. Thanks @sbine!
• Merged in change to count table th length after ajaxProcessing (pull #383). Thanks @harryxu!
• Reverted changes made in pull #349 as the error row was not showing because the urls did not exactly equal each other.
• Child rows within the pager will now properly display/hide. Fixes issue #348.
• Merged in fix for pager redundant ajax requests (pull #336). Thanks @camallen!
• Merged in fix for pager totalRows check (pull #324). Thanks @camallen!

Internal fixes

• Modified the pager plugin internal variables to use p for pager options and c for table config options - for consistency.
• Cleaned up the formatting of a few parsers (mostly cosmetic!)
• Some parser functions were added to the $.tablesorter object instead of keeping them as private functions, just because my OCD compelled me to do it.
• Some of the changes made the parsers are no longer backward compatible to the original version of tablesorter. Break away man, just do it!

Thanks

• Thanks to @thezoggy and @TheSin- for help maintaining and supporting the tablesorter github project while I was away!
• Also thanks to everyone else that contributed and even more thanks to those that helped troubleshoot and solve problems!

Version 2.10.8 (6/3/2013)

• Updated the percent parser to only detect if the content is shorter than 15 characters. This prevents columns with a lot of content and one percent sign (%) from being set to be parsed as a percent numeric column. Fixes issue #320.
• Updated filter widget & filter_formatter:
  • Added a new filter_defaultAttrib which points to the default 'data-value' attribute in the table header which will contain the filter's default (starting) value and will override any set values within the filter_formatter functions. Updated the custom filter widget function demo age column to show this in action.
  • The $.tablesorter.setFilter() method now properly updates the filter formatter elements when set.
  • The uiDateCompare and uiDatepicker functions now adds a time of 11:59:59 to the "to" date or when a "less than" comparison is made so as to include all times within that selected day.
  • The defaultDate option (not date option, sorry) of the uiDateCompare now properly sets the value upon initialization.
  • The from and to options of the uiDatepicker now properly sets those values properly upon initialization.
  • Fixes issue #321.
• Fixed stickyHeaders widget:
  • When removing a sticky headers widget, it no longer unbinds scrolling when other sticky headers are still active.
  • Added stickyHeaders_includeCaption option (set as true by default). When this option is false and a caption exists, it will not be included in teh sticky header. Fixes issue #322.

Version 2.10.7 (5/31/2013)

• Now using correct closest() function equivalent. Thanks to isuTony; Fixes issue #319.
• Anticipating my sabbitical, I've added a few "beta-testing" scripts into a new folder for feedback, code fixes and help:
  • Custom pager control script - should be working properly.
  • External filters using Select2 plugin - should be working properly.
  • Column reorder widget - not working 100% with sticky headers.
  • Column sum widget - still needs LOTS of work!