# tablesorter

## Writing custom parsers

### Flexible client-side table sorting

Back to documentation
Notes about the `addParser` template:

- The `id` block is required and must be unique.
- The `is` block will allow the parser to be used for autodetecting the parser
  - Most custom parsers are made for a specific set of data/column, so the `is` block usually just returns false telling the plugin that the parser doesn't match any columns.
  - If so desired, the function provides four parameters: `s` contains the text from the cell, `table` is the table DOM element, `cell` is the current cell DOM element and `$cell` is the current cell as a jQuery object (added v2.18.0).
  - This function must `return true` before the plugin will use the custom parser's format block to process the column content.
  - In version 2.7.4, the `is` block became optional because most parsers just return false.
- The `format` block is used to normalize your data and return it to the plugin for sorting
  - Within this function, modify the given text from the cell (`s`) or obtain parameters and/or other data from the cell (`cell`) then return this data to the plugin.
  - As an example, the date parser takes the date string (e.g. `"12/25/2013"`) and converts it into a numeric value (`1387951200000`; ref) to make sorting and comparing dates easier.
  - Use the `cellIndex` if the cells within columns contain different data - see this demo for an example.
- The `parsed` block (added v2.15.0)
  - This parameter is a flag used by the filter widget.
  - When `true`, the filter widget will only search through parsed data for matches.
  - If `false` (default value), the filter widget will search through the cell text for matches.
  - Currently, only the parsers for inputs, checkboxes and selects have this parameter set to `true`.
- The `type` block sets the type of sort to use:
  - Set it to either `"text"` or `"numeric"`.
  - This tells the plugin the type of sorter to use.
  - Text type sorting uses a natural sort and is a tiny bit slower than a pure numeric sort.

### Add Parser Template

    $.tablesorter.addParser({
      // use a unique id
      id: 'myparser',
      is: function(s, table, cell, $cell) {
        // s is the text from the cell
        // table is the current table (as a DOM element; not jQuery object)
        // cell is the current table cell (DOM element)
        // $cell is the current table cell (jQuery object; added v2.18.0)
        // return false if you don't want this parser to be auto detected
        return false;
      },
      format: function(s, table, cell, cellIndex) {
        // s is the text from the cell
        // table is the current table (as a DOM element; not jQuery object)
        // cell is the current table cell (DOM element)
        // cellIndex is the current cell's column index
        // format your data for normalization
        // (i.e. do something to get and/or modify your data, then return it)
        return s;
      },
      // flag for filter widget (true = ALWAYS search parsed values; false = search cell text)
      parsed: false,
      // set the type to either numeric or text (text uses a natural sort function
      // so it will work for everything, but numeric is faster for numbers
      type: 'numeric'
    });

# Demo

Name | Major | Gender | English | Japanese | Calculus | Overall grades
--- | --- | --- | --- | --- | --- | ---
Student01 | Languages | male | 80 | 70 | 75 | medium
Student02 | Mathematics | male | 90 | 88 | 100 | good
Student03 | Languages | female | 85 | 95 | 80 | good
Student04 | Languages | male | 20 | 50 | 65 | bad
Student05 | Mathematics | female | 70 | 78 | 70 | medium
Student06 | Mathematics | male | 44 | 65 | 60 | bad

# Javascript

### Grades Parser Code

# HTML

NOTE! Assigning the parser using a class name was added in version 2.0.11 (it is not part of the original plugin; use the `headers` option in older versions).

Next up: Writing custom parsers, advanced ››