<em>Note!</em> Version 2.0.3 of the tablesorter docs are available in russian, head over to <aclass="external"href="http://tablesorter.ru/docs/">tablesorter.ru</a>
<em>Helping out!</em> If you like tablesorter and you're feeling generous, take a look at my <aclass="external"href="http://www.amazon.com/gp/registry/wishlist/3VAOWCL63NEA6/ref=wl_web/">Amazon Wish List</a> or make a donation.
<li>Parsers for sorting text, URIs, integers, currency, floats, IP addresses, dates (ISO, long and short formats), time. <ahref="example-parsers.html">Add your own easily</a></li>
<em>NOTE!</em> tablesorter will auto-detect most data types including numbers, dates, ip-adresses for more information see <ahref="#Examples">Examples</a>
<li>*Note* you can use class names (version 2.0.11+, <ahref="example-parsers-class-name.html">demo</a>), or jQuery data (version 2.2.3+, <ahref="example-parsers-jquery-data.html">demo</a>) instead of meta data</li>
<li><ahref="example-meta-sort-list.html">Set a initial sorting order using metadata.</a></li>
<em>TIP!</em> Click on the link in the property column to reveal full details (or <ahref="#"class="toggleAll">toggle</a>|<ahref="#"class="showAll">show</a>|<ahref="#"class="hideAll">hide</a> all)
<td>Add this css class to a child row that should always be attached to its parent. Click on the "cssChildRow" link to toggle the view on the attached child row.</td>
As an example, I've split up this options table into three (3) tbodies. The first contains the active options, the second is the info block with a row that only contains the text "Deprecated Options", and the last tbody contains the deprecated options. Sort the table to see how each tbody sorts separately.
<br>
<pclass="tip">
<em>NOTE!</em> 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.
<td>This CSS class name can be applied to all rows that are to be removed prior to triggering a table update. <spanclass="tip"><em>New!</em></span> v2.1
<divclass="collapsible">
<br>
It was necessary to add this option because some widgets add table rows for styling (see the <ahref="example-widgets.html">writing custom widgets demo</a>) and if a table update is triggered (<codeclass="hilight">$('table').trigger('update');</code>) those added rows will automatically become incorporated into the table.
In previous versions, this option was set as "us", "uk" or "dd/mm/yy". This option was modified to better fit needed date formats. It will only work with four digit years!<br>
<br>
The sorter should be set to "shortDate" and the date format can be set in the "dateFormat" option or set for a specific columns within the "headers" option.
See <ahref="example-option-date-format.html">the demo page</a> to see it working.
<preclass="js">$(function(){
$("table").tablesorter({
dateFormat : "mmddyyyy", // default date format
// or to change the format for specific columns,
// add the dateFormat to the headers option:
headers: {
0: { sorter: "shortDate" }, // "shortDate" with the default dateFormat above
1: { sorter: "shortDate", dateFormat: "ddmmyyyy" }, // day first format
2: { sorter: "shortDate", dateFormat: "yyyymmdd" } // year first format
<td>Internal list of each header element as selected using jQuery selectors in the <ahref="#selectorheaders"><codeclass="hilight">selectorHeaders</code></a> option. Not really useful for normal usage.</td>
<td></td>
</tr>
<trid="headers">
<td><ahref="#"class="toggle2">headers</a></td>
<td>Object</td>
<td>null</td>
<td>
An object of instructions for per-column controls in the format: <codeclass="hilight">headers: { 0: { option: setting }, ... }</code>
<divclass="collapsible">
<br>
For example, to disable sorting on the first two columns of a table: <codeclass="hilight">headers: { 0: { sorter: false}, 1: {sorter: false} }</code>.<br>
<br>
The plugin attempts to detect the type of data that is contained in a column, but if it can't figure it out then it defaults to alphanumeric. You can easily override this by setting the header argument (or column parser).
This function is called when classes are added to the TH tags. You can use this to modify the HTML in each header tag for additional styling.
<divclass="collapsible">
<br>
In versions 2.0.6+, all TH text is wrapped in a span by default. In the example below, the header cell (TH) span is given a class name (<ahref="http://www.pengoworks.com/workshop/jquery/tablesorter/tablesorter.htm">source</a>).
<preclass="js">$(function(){
$("table").tablesorter({
onRenderHeader: function (){
$(this).find('span').addClass('roundedCorners');
}
});
});</pre>and you'll end up with this HTML (only the thead is shown)<preclass="html"><thead>
<tr><th><codeclass="hilight">sorter: "ipAddress"</code></th><td>Sort by IP Address.</td></tr>
<tr><th><codeclass="hilight">sorter: "url"</code></th><td>Sort by url.</td></tr>
<tr><th><codeclass="hilight">sorter: "isoDate"</code></th><td>Sort by ISO date (YYYY-MM-DD or YYYY/MM/DD).</td></tr>
<tr><th><codeclass="hilight">sorter: "percent"</code></th><td>Sort by percent.</td></tr>
<tr><th><codeclass="hilight">sorter: "usLongDate"</code></th><td>Sort by date (U.S. Standard, e.g. Jan 18, 2001 9:12 AM).</td></tr>
<tr><th><codeclass="hilight">sorter: "shortDate"</code></th><td>Sort by a shorten date (see <ahref="#dateformat"><codeclass="hilight">"dateFormat"</code></a>).</td></tr>
<tr><th><codeclass="hilight">sorter: "time"</code></th><td>Sort by time (23:59 or 12:59 pm).</td></tr>
<tr><th><codeclass="hilight">sorter: "metadata"</code></th><td>Sort by the sorter value in the metadata - requires the metadata plugin.</td></tr>
Check out the <ahref="#headers"><codeclass="hilight">headers</code></a> option to see how to use these parsers in your table (example #1).<br>Or add a header class name using "sorter-" plus the parser name (example #2), this includes custom parsers (example #3).
<td>jQuery selectors used to find the header cells. You can change this, but the table will still need the required thead and tbody before this plugin will work properly.</td>
<td></td>
</tr>
<trid="sortforce">
<td><ahref="#"class="toggle2">sortForce</a></td>
<td>Array</td>
<td>null</td>
<td>Use to add an additional forced sort that is <strong>prepended</strong> to <codeclass="hilight">sortList</code>.
<divclass="collapsible">
<br>
For example, <codeclass="hilight">sortForce: [[0,0]]</code> will sort the first column in ascending order. After the forced sort, the user selected column(s), or during initialzation, the sorting order defined in the sortList will follow. And lastly, the sort defined in the <ahref="#sortappend"><codeclass="hilight">sortAppend</code></a> option will be applied. More explicitly:<br>
<br>
There are three options to determine the sort order and this is the order of priority:
<ol>
<li><ahref="#sortforce"><codeclass="hilight">sortForce</code></a> forces the user to have this/these column(s) sorted first (null by default).</li>
<li><ahref="#sortlist"><codeclass="hilight">SortList</code></a> is the initial sort order of the columns.</li>
<li><ahref="#sortappend"><codeclass="hilight">SortAppend</code></a> is the default sort that is added to the end of the users sort selection (null by default).</li>
</ol>
The value of these sort options is an array of arrays and can include one or more columns. The format is an array of instructions for per-column sorting and direction in the format: <codeclass="hilight">[[columnIndex, sortDirection], ... ]</code> where <codeclass="hilight">columnIndex</code> is a zero-based index for your columns left-to-right and <codeclass="hilight">sortDirection</code> is 0 for Ascending and 1 for Descending. A valid argument that sorts ascending first by column 1 and then column 2 looks like: <codeclass="hilight">[[0,0],[1,0]]</code>.
<preclass="js">$(function(){
$("table").tablesorter({
sortForce : [[0,0]], // Always sort first column first
The value contains an array of instructions for per-column sorting and direction in the format: <codeclass="hilight">[[columnIndex, sortDirection], ... ]</code> where columnIndex is a zero-based index for your columns left-to-right and sortDirection is 0 for Ascending and 1 for Descending. A valid argument that sorts ascending first by column 1 and then column 2 looks like: <codeclass="hilight">[[0,0],[1,0]]</code>. Please see <ahref="#sortforce"><codeclass="hilight">sortForce</code></a> for more details on other sort order options.
<td>Use to add an additional forced sort that will be appended to the dynamic selections by the user.
<divclass="collapsible">
<br>
For example, can be used to sort people alphabetically after some other user-selected sort that results in rows with the same value like dates or money due. It can help prevent data from appearing as though it has a random secondary sort.<br>
<br>
The value contains an array of instructions for per-column sorting and direction in the format: <codeclass="hilight">[[columnIndex, sortDirection], ... ]</code> where <codeclass="hilight">columnIndex</code> is a zero-based index for your columns left-to-right and sortDirection is 0 for Ascending and 1 for Descending. A valid argument that sorts ascending first by column 1 and then column 2 looks like: <codeclass="hilight">[[0,0],[1,0]]</code>. Please see <ahref="#sortforce"><codeclass="hilight">sortForce</code></a> for more details on other sort order options.
When clicking the header for the first time, the direction it sorts. Valid arguments are <codeclass="hilight">"asc"</code> for Ascending or <codeclass="hilight">"desc"</code> for Descending.<br>
Boolean flag indicating if certain accented characters within the table will be replaced with their equivalent characters. <spanclass="tip"><em>Modified!</em></span> v2.2.
<li>This option no longer switches the sort to use the <codeclass="hilight">String.localeCompare</code> method.</li>
<li>When this option is <codeclass="hilight">true</code>, the text parsed from table cells will convert accented characters to their equivalent to allow the alphanumeric sort to properly sort.</li>
<li>If <codeclass="hilight">false</code> (default), any accented characters are treated as their value in the standard unicode order.</li>
<li>The following characters are replaced for both upper and lower case (information obtained from <ahref="http://sugarjs.com/sorting">sugar.js sorting equivalents</a> table):
<ul>
<li><codeclass="hilight">áàâãä</code> replaced with <codeclass="hilight">a</code></li>
<li><codeclass="hilight">ç</code> replaced with <codeclass="hilight">c</code></li>
<li><codeclass="hilight">éèêë</code> replaced with <codeclass="hilight">e</code></li>
<li><codeclass="hilight">íìİîï</code> replaced with <codeclass="hilight">i</code></li>
<li><codeclass="hilight">óòôõö</code> replaced with <codeclass="hilight">o</code></li>
<li><codeclass="hilight">úùûü</code> replaced with <codeclass="hilight">u</code></li>
<li><codeclass="hilight">ß</code> replaced with <codeclass="hilight">S</code></li>
</ul>
</li>
<li>Please see the example page for instrcutions on how to modify the above equivalency table.</li>
<li>If you would like to continuing using the <codeclass="hilight">String.localeCompare</code> method, then set the <codeclass="hilight">sortLocaleCompare</code> option to <codeclass="hilight">false</code> and use the new <codeclass="hilight">textSorter</code> option as follows:
<preclass="js">$('table').tablesorter({
textSorter: function(a,b) {
return a.localeCompare(b);
}
});</pre></li>
</ul>
<del>Boolean flag indicating whenever to use javascript <codeclass="hilight">String.localeCompare</code> method or not.<br>
This is only used when comparing text with international character strings. A sort using localeCompare will sort accented characters the same as their unaccented counterparts.</del>
Setting this option to <codeclass="hilight">true</code> will allow you to click on the table header a third time to reset the sort direction. New in v2.0.27.
Setting this option to <codeclass="hilight">true</code> will start the sort with the <codeclass="hilight">sortInitialOrder</code> when clicking on a previously unsorted column. New in v2.0.31.
<td>The key used to select more than one column for multi-column sorting. Defaults to the shift key. The other options are <codeclass="hilight">"ctrlKey"</code> or <codeclass="hilight">"altKey"</code>. Reference: <aclass="external"href="http://developer.mozilla.org/en/docs/DOM:event#Properties">http://developer.mozilla.org/en/docs/DOM:event#Properties</a></td>
Boolean flag indicating how tablesorter should deal with text inside of numerically sorted columns. <spanclass="tip"><em>New!</em></span> v2.1.16.
<divclass="collapsible"><br>
String options was initially set in the header options only. Overall option added and values changed in version 2.1.16; setting the value to:
<ul>
<li><codeclass="hilight">"max"</code> will treat any text in that column as a value greater than the <em>max</em> (more positive) value. Renamed from "max+".</li>
<li><codeclass="hilight">"min"</code> will treat any text in that column as a value greater than the <em>min</em> (more negative) value. Renamed from "max-".</li>
<li><codeclass="hilight">"top"</code> will always sort the text to the top of the column.</li>
<li><codeclass="hilight">"bottom"</code> will always sort the text to the bottom of the column.</li>
<li><codeclass="hilight">"none"</code> or <codeclass="hilight">"zero"</code> will treat the text as if it has a value of zero.</li>
</ul>
Individual columns can be modified by adding the following, set in order of priority:
The built-in option is <codeclass="hilight">"simple"</code> which is the equivalent of doing this inside of the textExtraction function: <codeclass="hilight">$(node).text();</code>.
tablesorter will pass the current table cell object for you to parse and return. Thanks to Josh Nathanson for the examples. Updated to a jQuery example by Rob G (Mottie).
<p>Now if the text you are finding in the script above is say a number, then just include the <ahref="#headers"><codeclass="hilight">headers</code></a> sorter option to specify how to sort it. Also in this example, we will specify that the special textExtraction code is only needed for the second column ("1" because we are using a zero-based index). All other columns will ignore this textExtraction function.</p>
<p>Added <codeclass="hilight">table</code> and <codeclass="hilight">cellIndex</code> variables to the <codeclass="hilight">textExtraction</code> function in version 2.1.2.</p>
Initialize widgets using this option ( e.g. <codeclass="hilight">widgets : ['zebra']</code>, or custom widgets <codeclass="hilight">widgets: ['zebra', 'myCustomWidget'];</code>, see <ahref="example-widgets.html">this demo</a> on how to write your own custom widget ).
As of version 2.1, all widget options have been moved into this option. This is a move to store all widget specific options in one place so as not to polute the main table options. All current widgets have been modified to use this new option. <spanclass="tip"><em>New!</em></span> in v2.1.
Previously documented widget options <ahref="#widgetzebra"><codeclass="hilight">widgetZebra</code></a>, <ahref="#widgetcolumns"><codeclass="hilight">widgetColumns</code></a> and <ahref="#widgetuitheme"><codeclass="hilight">widgetUitheme</code></a> will be retained for backwards compatibility.<br>
<br>
Use the <ahref="#widgetoptions"><codeclass="hilight">widgetOptions</code></a> option as follows, please note that each option is followed by a comma (except the last one):
It has been replaced by <ahref="#widget-columns"><codeclass="hilight">widgetOptions.columns</code></a>; but is still available for backwards compatibility.
When the column styling widget is initialized, it automatically applied the default class names of <codeclass="hilight">"primary"</code> for the primary sort, <codeclass="hilight">"secondary"</code> for the next sort, <codeclass="hilight">"tertiary"</code> for the next sort, and so on (add more as needed)... New in v2.0.17.
Use the <ahref="#widgetcolumns"><codeclass="hilight">widgetColumns</code></a> option to change the css class name as follows:
It has been replaced by <ahref="#widget-uitheme"><codeclass="hilight">widgetOptions.uitheme</code></a>; but is still available for backwards compatibility.
Used when the ui theme styling widget is initialized. It automatically applies the default class names of <codeclass="hilight">"ui-icon-arrowthick-2-n-s"</code> for the unsorted column, <codeclass="hilight">"ui-icon-arrowthick-1-s"</code> for the descending sort and <codeclass="hilight">"ui-icon-arrowthick-1-n"</code> for the ascending sort. New in v2.0.9.
Find more jQuery UI class names by hovering over the Framework icons on this page: <aclass="external"href="http://jqueryui.com/themeroller/">http://jqueryui.com/themeroller/</a><br>
It has been replaced by <ahref="#widget-zebra"><codeclass="hilight">widgetOptions.zebra</code></a>; but is still available for backwards compatibility.
When the zebra striping widget is initialized, it automatically applied the default class names of <codeclass="hilight">"even"</code> and <codeclass="hilight">"odd"</code>.
Use the <ahref="#widgetzebra"><codeclass="hilight">widgetZebra</code></a> option to change the css class name as follows:
<preclass="js">$(function(){
$("table").tablesorter({
widgets: ["zebra"], // initialize zebra striping of the table
widgetZebra: { css: [ "normal-row", "alt-row" ] }
});
});</pre></div>
</td>
<td></td>
</tr>
</tbody>
</table>
<aid="Widget-options"></a>
<h1>Widget Options</h1>
<pclass="tip">
tablesorter widgets have many options, and to better organize them, they now are grouped together inside of the <codeclass="hilight">widgetOptions</code><br>
<em>TIP!</em> Click on the link in the property column to reveal full details (or <ahref="#"class="toggleAll">toggle</a>|<ahref="#"class="showAll">show</a>|<ahref="#"class="hideAll">hide</a> all)
columns widget: When the column styling widget is initialized, it automatically applied the default class names of <codeclass="hilight">"primary"</code> for the primary sort, <codeclass="hilight">"secondary"</code> for the next sort, <codeclass="hilight">"tertiary"</code> for the next sort, and so on (add more as needed)... <spanclass="tip"><em>Modified!</em></span> in v2.1.
<divclass="collapsible">
<br>
Use the <ahref="#widget-columns"><codeclass="hilight">"columns"</code></a> option to change the css class name as follows:
<preclass="js">$(function(){
$("table").tablesorter({
widgets: ["columns"], // initialize column styling of the table
Filter widget: If there are child rows in the table (rows with class name from <ahref="#csschildrow"><codeclass="hilight">"cssChildRow"</code></a> option) and this option is <codeclass="hilight">true</code> and a match is found anywhere in the child row, then it will make that row visible.
<spanclass="tip"><em>Modified!</em></span> in v2.1.
<divclass="collapsible">
<br>
Use the <ahref="#widget-filter-childrows"><codeclass="hilight">filter_childRows</code></a> option include child row text as follows:
Filter widget: This is the class name applied to the filter header row (tr) and each input within that row. If you change it from the default class name of <codeclass="hilight">"tablesorter-filter"</code> make sure you also update the css!
<spanclass="tip"><em>New!</em></span> in v2.1.
<divclass="collapsible">
<br>
Use the <ahref="#widget-filter-cssfilter"><codeclass="hilight">"tablesorter-filter"</code></a> option to change the css class name as follows:
<preclass="js">$(function(){
$("table").tablesorter({
widgets: ["filter"],
widgetOptions : {
// css class applied to the table row containing the filters & the inputs within that row
Filter widget: Set this option to <codeclass="hilight">true</code> to use the filter to find text from the start of the column, so typing in "a" will find "albert" but not "frank", both have a's.
stickyHeaders widget: This is the class name applied to the sticky header row (tr). If you change it from the default class name of <codeclass="hilight">"tablesorter-stickyHeader"</code> make sure you also update the css!
<spanclass="tip"><em>New!</em></span> in v2.1.
<divclass="collapsible">
<br>
Use the <ahref="#widget-sticky-headers"><codeclass="hilight">"stickyHeaders"</code></a> option to change the css class name as follows:
uitheme widget: This widget option replaces the previous <ahref="#widgetuitheme">widgetUitheme</a>. It is used when the ui theme styling widget is initialized. It automatically applies the default class names of <codeclass="hilight">"ui-icon-arrowthick-2-n-s"</code> for the unsorted column, <codeclass="hilight">"ui-icon-arrowthick-1-s"</code> for the descending sort and <codeclass="hilight">"ui-icon-arrowthick-1-n"</code> for the ascending sort. <spanclass="tip"><em>Modified!</em></span> in v2.1.
<divclass="collapsible">
<br>
Find more jQuery UI class names by hovering over the Framework icons on this page: <aclass="external"href="http://jqueryui.com/themeroller/">http://jqueryui.com/themeroller/</a><br>
<br>
Use the <ahref="#widgetuitheme"><codeclass="hilight">"widgetUitheme"</code></a> option to change the css class name as follows:
<preclass="js">$(function(){
$("table").tablesorter({
widgets: ["uitheme"], // initialize ui theme styling widget of the table
zebra widget: When the zebra striping widget is initialized, it automatically applied the default class names of <codeclass="hilight">"even"</code> and <codeclass="hilight">"odd"</code>. <spanclass="tip"><em>Modified!</em></span> in v2.1.
<divclass="collapsible">
<br>
Use the <ahref="#widget-zebra"><codeclass="hilight">"zebra"</code></a> option to change the css class name as follows:
<preclass="js">$(function(){
$("table").tablesorter({
widgets: ["zebra"], // initialize zebra striping of the table
tablesorter has some methods available to allow updating, resorting or applying widgets to a table after it has been initialized.
<br>
<em>TIP!</em> Click on the link in the method column to reveal full details (or <ahref="#"class="toggleAll">toggle</a>|<ahref="#"class="showAll">show</a>|<ahref="#"class="hideAll">hide</a> all):
<td>Update a table that has had its data dynamically changed; used in conjunction with "update".<br>
<divclass="collapsible">
Use this method when more than just one cell like in the "updateCell" method, but you may possibly have to trigger two events: both "update" and "appendCache".<br>
<br>
Note: This is the only method the pager widget uses - the entire table is stored in the cache, but only the visible portion is actually exists in the table.
<preclass="js">// Table data was just dynamically changed (more than one cell)
<td>Apply the selected widget to the table, but the widget will not continue to be applied after each sort. See the example, it's easier than describing it.
<td>Apply the set widgets to the table. This method can be used after a table has been initialized, but it won't work unless you update the configuration settings. See the example, it's easier than describing it.
<divclass="collapsible">
<preclass="js">// Update the list of widgets to apply to the table (add or remove)
tablesorter has some methods available to allow updating, resorting or applying widgets to a table after it has been initialized.
<br>
<em>TIP!</em> Click on the link in the event column to reveal full details (or <ahref="#"class="toggleAll">toggle</a>|<ahref="#"class="showAll">show</a>|<ahref="#"class="hideAll">hide</a> all):
<p><strong>Pick n choose</strong> - Place at least the required files in a directory on your webserver that is accessible to a web browser. Record this location.</p>
<li><aclass="external"href="http://docs.jquery.com/Downloading_jQuery#Download_jQuery">jQuery</a> (1.2.6 or higher; some demos need jQuery 1.4.2+)</li>
<li><ahref="../js/jquery.tablesorter.widgets.js">jquery.tablesorter.widgets.js</a> (16kb/<ahref="../js/jquery.tablesorter.widgets.min.js">8kb min</a>, includes the jQuery UI theme, columns styling, resizable columns, filter, sticky header and save sort widgets. <spanclass="tip"><em>Updated!</em></span> in v2.1.)</li>
<li><ahref="example-widget-ui-theme.html">jQuery UI Theme</a> - Apply any jQuery UI theme to the table using the "uitheme" widget code. New in v2.0.9!</li>
<p>If you are having a problem with the plugin or you want to submit a feature request, please <ahref="https://github.com/Mottie/tablesorter/issues">submit an issue</a>.</p>
<p>If you would like to contribute, <ahref="https://github.com/Mottie/tablesorter">fork a copy on github</a>.</p>
<p>Support is also available through the <aclass="external"href="http://jquery.com/discuss/">jQuery Mailing List</a> or <aclass="external"href="http://stackoverflow.com/questions/tagged/tablesorter">StackOverflow</a>.</p>
<p>Access to the jQuery Mailing List is also available through <aclass="external"href="http://www.nabble.com/JQuery-f15494.html">Nabble Forums</a>.</p>
Missing documentation, alphanumeric sort, numerous widgets and other changes added by <aclass="external"href="https://github.com/Mottie/tablesorter">Mottie</a>.
