# tablesorter

## Writing custom widgets

### Flexible client-side table sorting

Back to documentation
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.
- 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.
- 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` and `widgetOptions` were provided as additional parameters (sorry the previous docs were incorrect).
  - The `initFlag` is correctly set in v2.8+.
- The `remove` block (added v2.4):
  - In 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 widget `init` 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.
  - This code is called when either the `refreshWidgets` or `destroy` 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.

### 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
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
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
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
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
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

Next up: Pager plugin ››