Notes about the
addWidget
template:
- The
id
block:- The widget id, or name, must be unique!
- The id, or name, can contain special characters and/or spaces.
- This setting is required.
- The
priority
block (added v2.9):- Set the widget priority using any number; think of it like setting the css z-index.
- This tells the plugin the order in which to run the widgets, lowest number priority first.
- The default widgets have priorities set in intervals of 10 (see the widget priority table), so to run your custom widget before a specific widget, set your widget priority to less than that number.
- This block is not supported in older versions!
- This setting is optional, but if no priority is specified, it defaults to
10
.
- The
options
block (added v2.8):- Include any widget options to be automatically be extended with any set widgetOptions (from
table.config.widgetOptions
). - As of v2.8, no included widgets will be using this to maintain backwards compatibility with older versions. This changed when v2.9 was released.
- This block is not supported in older versions!
- This block is optional.
- Include any widget options to be automatically be extended with any set widgetOptions (from
- The
init
block (added v2.0.28):- This code is called only after tablesorter has initialized, but before initial sort and before any of the widgets are applied (via the
format
block); it is only run once. - Since, v2.0.28, only the saveSort widget uses this block to ensure that the stored sort is applied before; but some of the newer widgets (post v2.9) are using this code block.
- This block is not supported in older versions.
- This block is optional.
- This code is called only after tablesorter has initialized, but before initial sort and before any of the widgets are applied (via the
- The
format
block (modified v2.0.23):- This block is part of the original
addWidget
template and is required. - In the original template, only the
table
parameter is provided. After v2.0.28,config
andwidgetOptions
were provided as additional parameters (sorry the previous docs were incorrect). - The
initFlag
is correctly set in v2.8+.
- This block is part of the original
- The
remove
block (added v2.4):- In New v2.19.0 the
refreshing
parameter was added:- It is a parameter used to indicate that the
refreshWidgets
method was triggered. - When widgets are refreshed, the
remove
method is called, then the widgetinit
function is immediately called to reapply the widget. - In this update, this parameter is used by the filter widget to retain filtered rows and prevent a "flash" of showing all rows, then returning to its previous state after applying the filter again.
- It is a parameter used to indicate that the
- This code is called when either the
refreshWidgets
ordestroy
methods are called. - The code contained within this block must remove all additional content/elements added by the widget. Also, any rows or content that is hidden must be restored.
- If additional rows are added to the table, make sure to include the class name within the
selectorRemove
option. - This block was added in v2.4, and not supported in older versions.
- This block is optional.
- In New v2.19.0 the
addWidget Template
// addWidget Template
// *******************
// parameters:
// table = table object (DOM)
// config = config object (from table.config)
// widgetOptions = all widget options (from table.config.widgetOptions)
$.tablesorter.addWidget({
id: 'myWidget',
// set the priority of the widget (optional)
priority: 10,
// widget options (added v2.8) - added to table.config.widgetOptions
options: {
myWidget_option1 : 'setting1',
myWidget_option2 : 'setting2'
},
// The init function (added v2.0.28) is called only after tablesorter has
// initialized, but before initial sort & before any of the widgets are applied.
init: function(table, thisWidget, config, widgetOptions){
// widget initialization code - this is only *RUN ONCE*
// but in this example, only the format function is called to from here
// to keep the widget backwards compatible with the original tablesorter
thisWidget.format(table, config, widgetOptions, true);
},
format: function(table, config, widgetOptions, initFlag) {
// widget code to apply to the table *AFTER EACH SORT*
// set the initFlag to true when this format is called from the init
// function above otherwise initFlag is undefined
// * see the saveSort widget for a full example *
},
remove: function(table, config, widgetOptions, refreshing){
// do what ever needs to be done to remove stuff added by your widget
// unbind events, restore hidden content, etc.
// refreshing flag is true when the refreshWidgets method is triggered, meaning
// the widget will be removed, then immediately reapplied
}
});
Demo
Name | Major | Sex | English | Japanese | Calculus | Geometry |
---|---|---|---|---|---|---|
Name | Major | Sex | English | Japanese | Calculus | Geometry |
Student12 | Mathematics | female | 100 | 75 | 70 | 85 |
Student13 | Languages | female | 100 | 80 | 100 | 90 |
Student14 | Languages | female | 50 | 45 | 55 | 90 |
Student15 | Languages | male | 95 | 35 | 100 | 90 |
Name | Major | Sex | English | Japanese | Calculus | Geometry |
Student16 | Languages | female | 100 | 50 | 30 | 70 |
Student17 | Languages | female | 80 | 100 | 55 | 65 |
Student18 | Mathematics | male | 30 | 49 | 55 | 75 |
Student19 | Languages | male | 68 | 90 | 88 | 70 |
Name | Major | Sex | English | Japanese | Calculus | Geometry |
Student20 | Mathematics | male | 40 | 45 | 40 | 80 |
Student21 | Languages | male | 50 | 45 | 100 | 100 |
Student22 | Mathematics | male | 100 | 99 | 100 | 90 |
Student23 | Languages | female | 85 | 80 | 80 | 80 |
Name | Major | Sex | English | Japanese | Calculus | Geometry |
Student01 | Languages | male | 80 | 70 | 75 | 80 |
Student02 | Mathematics | male | 90 | 88 | 100 | 90 |
Student03 | Languages | female | 85 | 95 | 80 | 85 |
Student04 | Languages | male | 60 | 55 | 100 | 100 |
Name | Major | Sex | English | Japanese | Calculus | Geometry |
Student05 | Languages | female | 68 | 80 | 95 | 80 |
Student06 | Mathematics | male | 100 | 99 | 100 | 90 |
Student07 | Mathematics | male | 85 | 68 | 90 | 90 |
Student08 | Languages | male | 100 | 90 | 90 | 85 |
Name | Major | Sex | English | Japanese | Calculus | Geometry |
Student09 | Mathematics | male | 80 | 50 | 65 | 75 |
Student10 | Languages | male | 85 | 100 | 100 | 90 |
Student11 | Languages | male | 86 | 85 | 100 | 100 |
Student24 | Languages | female | 100 | 91 | 13 | 82 |
Javascript
Repeat Headers Widget
$(function() {
// add new widget called repeatHeaders
// updated v2.18.0 (works in nested tables)
// *****************************************
$.tablesorter.addWidget({
id: "repeatHeaders",
priority: 10,
options: {
rowsToSkip : 4
},
// format is called on init and when a sorting has finished
format: function(table, c, wo) {
var h = '', i, $tr, l, skip;
// cache and collect all TH headers
if (!wo.repeatHeaders) {
// "remove-me" class was added in case the table needs to be updated, the "remove-me" rows will be
// removed prior to the update to prevent including the rows in the update - see "selectorRemove" option
h = '<tr class="repeated-header remove-me">';
$.each(c.headerContent, function(i,t) {
// table.config.headerContent stores the original table HTML (as text), but it is the HTML before
// the headerTemplate option is applied to each header cell; and before the `onRender` callbacks are
// executed
h += '<th>' + t + '</th>';
});
wo.repeatHeaders = h + '</tr>';
}
// number of rows to skip
skip = wo && wo.rowsToSkip || 4;
// remove appended headers by classname
c.$tbodies.children("tr.repeated-header").remove();
// only find visible rows (may be filtered)
$tr = c.$tbodies.children('tr:visible');
l = $tr.length;
// loop all tr elements and insert a copy of the "headers"
for (i = skip; i < l; i += skip) {
// insert a copy of the table head every X rows
$tr.eq(i).before(wo.repeatHeaders);
}
},
// this remove function is called when using the refreshWidgets method or when destroying the tablesorter plugin
// this function only applies to tablesorter v2.4+
remove: function(table, c){
c.$tbodies.children("tr.repeated-header").remove();
}
});
// call the tablesorter plugin and assign widgets with id "zebra" (Default widget in the core) and the newly created "repeatHeaders"
$("table").tablesorter({
theme: 'blue',
// apply both widgets
widgets: ['zebra', 'repeatHeaders'],
widgetOptions : {
rowsToSkip : 4
}
});
});