tablesorter/README.markdown

133 lines
23 KiB
Markdown
Raw Normal View History

<EFBFBD><EFBFBD>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](http://mottie.github.com/tablesorter/docs/).
* All of the [original document pages](http://tablesorter.com/docs/) have been included.
* Information from my blog post on [undocumented options](http://wowmotty.blogspot.com/2011/06/jquery-tablesorter-missing-docs.html) and lots of new demos have also been included.
* Change log moved from included text file into the [wiki documentation](https://github.com/Mottie/tablesorter/wiki/Change).
### Demos
* [Basic alpha-numeric sort Demo](http://mottie.github.com/tablesorter/).
* Links to demo pages can be found within the main [documentation](http://mottie.github.com/tablesorter/docs/).
* More demos & playgrounds - updated in the [wiki pages](https://github.com/Mottie/tablesorter/wiki).
### Features
* Multi-column sorting.
* Multi-tbody sorting - see the [options](http://mottie.github.com/tablesorter/docs/index.html#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) &amp; time. [Add your own easily](http://mottie.github.com/tablesorter/docs/example-parsers.html).
* 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](http://mottie.github.com/tablesorter/docs/example-widgets.html).
* Cross-browser: IE 6.0+, FF 2+, Safari 2.0+, Opera 9.0+.
* Small code size.
2012-05-08 19:46:13 +00:00
* Works with jQuery 1.2.6+.
### Licensing
* Copyright (c) 2007 Christian Bach.
* Original examples and docs at: [http://tablesorter.com](http://tablesorter.com).
* Dual licensed under the [MIT](http://www.opensource.org/licenses/mit-license.php) and [GPL](http://www.gnu.org/licenses/gpl.html) licenses.
### Change Log
View the [complete listing here](https://github.com/Mottie/tablesorter/wiki/Change).
2012-05-28 15:22:42 +00:00
#### Version 2.3.5 (5/28/2012)
2012-05-28 15:01:40 +00:00
2012-05-28 15:22:42 +00:00
* Fixed colspan in header causing javascript errors and metadata issues. Fix for [issue #78](https://github.com/Mottie/tablesorter/issues/78).
* Fixed Chrome "Uncaught RangeError" issue. Fix for [issue #70](https://github.com/Mottie/tablesorter/issues/70).
2012-05-28 15:01:40 +00:00
* Added more optimizations to speed up IE (except IE7):
* Hide tbody during manipulation - added "tablesorter-hidden" css definition.
* Parsing of the table contents using `textContent` for modern browsers (including IE9); see [this jsperf](http://jsperf.com/read-innerhtml-vs-innertext-vs-nodevalue-vs-textcontent).
* Columns widget.
* Filter widget.
* Zebra widget.
* Updated the shortDate detection regex to look for two or four grouped digits instead of two through four digits. Fix for [issue #76](https://github.com/Mottie/tablesorter/issues/76).
* Widget updates:
* Added `initWidgets` option
* If `true`, all selected widgets (from the `widgets` option) will be applied after the table has initialized.
* when `false`, selected widgets `init` function will be called, but not the `format` function. So none of the widget formating will be applied to the table. Note: almost all included widgets do not use the `init` function to keep backward compatibility, except for the `saveSort` widget in which the `init` function immediately calls the `format` function. This information is only important if you are writing a custom widget.
* It would be useful to set this option to false if using the pager plugin along with a very large table, say 1000+ rows. The table will be initialized, but no widgets are applied. Then the pager plugin is called and the table is modified and all of the widgets are applied when completed. So essentially this saves time by only running the widgets once.
* Modified the pager plugin to make sure it doesn't apply widgets more than once.
* Added filter widget option `filter_ignoreCase`:
* The default setting is `true` and all searches will be case insensitive.
* Set this option to `false` to make the searches case sensitive.
* Added filter widget option `filter_searchDelay`:
* Default set to 300 milliseconds.
* This is the delay before the filter widget starts searching.
* This option prevents searching for every character while typing and should make searching large tables faster.
* Resizable widget will no longer initialize a sort after releasing the mouse.
2012-05-28 15:22:42 +00:00
* Updated ui theme css to remove bold fonts from odd rows.
2012-05-28 15:01:40 +00:00
2012-05-20 13:24:22 +00:00
#### Version 2.3.4 (5/20/2012)
* Added selector change suggested by [AnthonyM1229](https://github.com/AnthonyM1229) in [issue #74](https://github.com/Mottie/tablesorter/issues/74#issuecomment-5806832) to fix IE8 ignoring class name parsers. Thanks again Anthony for all of your hard work and input!
2012-05-19 20:46:14 +00:00
#### 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](https://github.com/Mottie/tablesorter/issues/73),
* and fix [issue #74](https://github.com/Mottie/tablesorter/issues/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](http://mottie.github.com/tablesorter/docs/example-triggers.html) 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](http://mottie.github.com/tablesorter/docs/example-option-date-format.html).
* [Lock sort order](http://mottie.github.com/tablesorter/docs/example-options-headers-locked.html).
* [Initial sort order](http://mottie.github.com/tablesorter/docs/example-options-headers-order.html).
* [Set parser by class name](http://mottie.github.com/tablesorter/docs/example-parsers-class-name.html).
* [Disable filter widget](http://mottie.github.com/tablesorter/docs/example-widget-filter.html). NOTE: this widget uses the `getData()` function that doesn't exist in the original tablesorter.
2012-05-11 17:46:54 +00:00
#### 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]);`.
2012-05-11 18:14:44 +00:00
* Fixed percent parser to not be automatically applied to text columns. Fix for [issue #67](https://github.com/Mottie/tablesorter/issues/67).
2012-05-11 17:46:54 +00:00
* 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](https://github.com/kristerkari) in [pull request #68](https://github.com/Mottie/tablesorter/pull/68).
* Updated [multiple tbodies demo](http://mottie.github.com/tablesorter/docs/example-multiple-tbodies.html).
* 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](http://mottie.github.com/tablesorter/docs/example-parsers-advanced.html) 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`](http://mottie.github.com/tablesorter/docs/index.html#dateformat)
* [`lockedOrder`](http://mottie.github.com/tablesorter/docs/index.html#headers) - no demo.
* [`sortInitialOrder`](http://mottie.github.com/tablesorter/docs/index.html#sortinitialorder)
* [`filter`](http://mottie.github.com/tablesorter/docs/index.html#headers) widget - no demo.
* Added the ability to set the `sortList` via jQuery data. See the updated [sortList](http://mottie.github.com/tablesorter/docs/index.html#sortlist) documents on how to use it
* Fixed date parsers (isoDate, usLongDate, shortDate and time) which did not handle empty cell data properly.
2012-05-08 19:46:13 +00:00
#### 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](http://mottie.github.com/tablesorter/docs/example-header-column-span.html).
* Added support for "Content-type: application/xhtml+xml". Fix for [issue #62](https://github.com/Mottie/tablesorter/issues/62). Thanks to [MelTraX](https://github.com/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](https://github.com/MelTraX) in [issue #66](https://github.com/Mottie/tablesorter/issues/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](http://mottie.github.com/tablesorter/docs/index.html#parsers), [stringTo](http://mottie.github.com/tablesorter/docs/index.html#stringto) and [emptyTo](http://mottie.github.com/tablesorter/docs/index.html#emptyto) options.
* Nested tables will no longer be targeted inappropriately. Fix for [issue #65](https://github.com/Mottie/tablesorter/issues/65). Thanks to [MelTraX](https://github.com/MelTraX) for sharing some code!
* Reordered parsers to detect other numeric parsers before the general one. Fix for [issue #64](https://github.com/Mottie/tablesorter/issues/64).
* Completed minor document corrections, general code cleanup, optimization and removal of a global variable.