jQuery plugin: Tablesorter 2.0 - Custom Filter Widget Functions

# tablesorter

## Custom Filter Widget Functions

### Flexible client-side table sorting

Back to documentation

### Notes

- In v2.21.0, the filter functions provide an additional parameter `c` which is the `table.config`.
- In v2.17.0, the `filter_functions` column can also be referenced by using a jQuery selector (e.g. class name or ID).
- In v2.16.3,
  - When a default filter select is added to a column, it is now parsed from the assigned parser, then sorted using the `textSorter` setting, and falls back to an alphanumeric sort.
  - Adding a class of `"filter-select-nosort"` will now leave the select options unsorted.
- In v2.14, the `filter_saveFilters` option was added (default set to `false`); this demo has it set to `true` to provide an example.
- In v2.11, the filter functions provide an additional parameter `$r` providing a jQuery object of the current row being searched by the filter.
- For v2.10.8, the Age column includes the new `data-value` set to `<30` which sets the default (starting) filter value (see filter_defaultAttrib for more details).
- As of tablesorter v2.9, this widget can no longer be applied to versions of tablesorter prior to version 2.8.
- Custom filter widget option `filter_functions` was added in version 2.3.6.
- jQuery v1.4.3+ required.

### Default Select ("First Name" column)

- To enable this type of select, set the `filter_functions` option for the column to `true`,

      filter_functions : {

        // Add select menu to this column
        // set the column value to true, and/or add "filter-select" class name to header
        '.first-name' : true

      }

  or add a "filter-select" class to the column header cell (see code below).
- The default option text, "Select a name", is obtained from the header `data-placeholder` attribute of the column header cell. And when active, it will show all table rows.

      <th class="filter-select" data-placeholder="Select a name">First Name</th>

- Add a "filter-match" class to only match instead of exactly match the selected value. Click on the "Match" button below to see the difference.

      <th class="filter-select filter-match" data-placeholder="Select a name">First Name</th>

- The select is populated by the column text contents with repeated content combined (i.e. There are three "Aaron"'s in the first column, but only one in the dropdown.
- Select options are automatically alphanumerically (new in v2.4) sorted. Changed in v2.16.3:
  - The select contents are now parsed from the assigned parser, then sorted using the `textSorter` option
  - Add a class name of `"filter-select-nosort"` to prevent sorting the select options (v2.16.3).
- Please check out what the "filter-onlyAvail" class name does by reviewing the details below (in the "Discount" column) (v2.10.1).

### Custom Filter Function ("Last Name" column)

- To enable this type of filter, add your custom function to the `filter_functions` option following this example:

      filter_functions : {

        // Exact match only
        1 : function(e, n, f, i, $r, c) {
          return e === f;
        }

      }

- The example shows you how to show only exact matches. The problem with this is that you can't see the matches while typing unless you set the `filter_searchDelay` option to be a bit longer.
- Also, the example only checks for an exact match (`===`) meaning the `filter_ignoreCase` option is ignored, but other comparisons can be made using regex and the insensitive "i" flag.
- See the filter function information below.

### Custom Select ("City" or "Total" column)

- To enable this type of select, add your custom options within the `filter_functions` option.
- Each option is set as a "key:value" pair where the "key" is the actual text of the option and the "value" is the function associated with the option.
- Here is an example using alphabetical comparisons (using regular expressions):

      filter_functions : {

        // Add these options to the select dropdown (regex example)
        2 : {
          "A - D" : function(e, n, f, i, $r, c) { return /^[A-D]/.test(e); },
          "E - H" : function(e, n, f, i, $r, c) { return /^[E-H]/.test(e); },
          "I - L" : function(e, n, f, i, $r, c) { return /^[I-L]/.test(e); },
          "M - P" : function(e, n, f, i, $r, c) { return /^[M-P]/.test(e); },
          "Q - T" : function(e, n, f, i, $r, c) { return /^[Q-T]/.test(e); },
          "U - X" : function(e, n, f, i, $r, c) { return /^[U-X]/.test(e); },
          "Y - Z" : function(e, n, f, i, $r, c) { return /^[Y-Z]/.test(e); }
        }

      }

- Here is an example using numerical comparisons:

      filter_functions : {
        // Add these options to the select dropdown (numerical comparison example)
        // Note that only the normalized (n) value will contain numerical data
        // If you use the exact text, you'll need to parse it (parseFloat or parseInt)
        4 : {
          "< $10"      : function(e, n, f, i, $r, c) { return n < 10; },
          "$10 - $100" : function(e, n, f, i, $r, c) { return n >= 10 && n <=100; },
          "> $100"     : function(e, n, f, i, $r, c) { return n > 100; }
        }
      }

- See the "Filter function information" section below.

### Default Select with only available options ("Discount" column)

- This column uses the same method as the "First Name" column with one exception, it also includes the "filter-onlyAvail" class name in the header cell:

      <th class="filter-select filter-onlyAvail">Discount</th>

- To see how this works, do the following:
  - First, filter the "First Name" column by selecting the name "Clark"
  - Now use the "Discount" filter select box, you'll notice that only the values associated with the first name of Clark are showing as options.
- Conversely, if you reset the filters, select "44%" in the "Discount" column, then look at the "First Name" filter selector, you'll notice that it still contains all of the original options; because the "filter-onlyAvail" class name is not included in that column's header cell.
- Sorry, this functionality only works for default select filters.
- This funcitonality was added in v2.10.1.

### Filter function information

- The custom function must return a boolean value. If `true` is returned, the row will be shown if all other filters match; and if `false` is returned, the row will be hidden.

      function(e, n, f, i, $r, c) { return test; /* test should be a Boolean (true or false) */ }

- The exact text (e) of the table cell is a variable passed to the function. Note that numbers will need to be parsed to make comparisons.
- Normalized table cell data (n) is the next varibale passed to the function.
  - This data has been parsed by the assigned column parser, so make sure the same type of data is being compared as parsed data may not be what you expect.
  - Normalized numerical values within the table will be of numeric type and not of string type, as the sorter needs to use mathematical comparisons while sorting.
  - The data will be in lower-case if the `filter_ignoreCase` option is `true`.
  - Dates like in the last column of the table below will store the time in seconds since 1970 (using javascript's .getTime() function).
  - The percentage column will only store the number and not percentage sign.
- The filter input value (f) is the exact text entered by the user. If numerical, it will need to be parsed using parseFloat() or parseInt() to allow for making comparisons.
- The column index (i) might be useful for obtaining more information from header, or something.
- The row ($r) is the current table row (jQuery object) being searched (or filtered).
  - This allows access to any extra information within. To access the current cell, just use `$r.children().eq(i)`.
  - * NOTE * The row object provided is not attached to the table, so using something like `.parent()` or `.closest()` will not work!
  - For this reason, the next parameter (`c`) was added.
- The config (c) is the `table.config` (added v2.21.0).

# Demo

false (toggle "filter-match" class on First Name column)

First Name | Last Name | City | Age | Total | Discount | Date
--- | --- | --- | --- | --- | --- | ---
Aaron | Johnson Sr | Atlanta | 35 | $5.95 | 22% | Jun 26, 2004 7:22 AM
Aaron | Johnson | Yuma | 12 | $2.99 | 5% | Aug 21, 2009 12:21 PM
Clark | Henry Jr | Tampa | 51 | $42.29 | 18% | Oct 13, 2000 1:15 PM
Denni | Henry | New York | 28 | $9.99 | 20% | Jul 6, 2006 8:14 AM
John | Hood | Boston | 33 | $19.99 | 25% | Dec 10, 2002 5:14 AM
Clark | Kent Sr | Los Angeles | 18 | $15.89 | 44% | Jan 12, 2003 11:14 AM
Peter | Kent Esq | Seattle | 45 | $153.19 | 44% | Jan 18, 2021 9:12 AM
Peter | Johns | Milwaukee | 13 | $5.29 | 4% | Jan 8, 2012 5:11 PM
Aaron | Evan | Chicago | 24 | $14.19 | 14% | Jan 14, 2004 11:23 AM
Bruce | Evans | Upland | 22 | $13.19 | 11% | Jan 18, 2007 9:12 AM
Clark | McMasters | Pheonix | 18 | $55.20 | 15% | Feb 12, 2010 7:23 PM
Dennis | Masters | Indianapolis | 65 | $123.00 | 32% | Jan 20, 2001 1:12 PM
John | Hood | Fort Worth | 25 | $22.09 | 17% | Jun 11, 2011 10:55 AM

# Javascript

# HTML

Next up: Custom Filter Widget Search Types ››