# tablesorter

## Grouping Rows Widget

### Flexible client-side table sorting

Back to documentation

### Notes

- This widget will only work in tablesorter version 2.8+ and jQuery version 1.7+.
- Please do not use this widget in very large tables (it might be really slow) or when your table includes multiple tbodies.
- In v2.13, added `group_separator` option & `group-separator-#` header class name. To see this in action, check out the file type parser demo.
- In v2.12, added `group_callback` & `group_complete` options. See options section below for details.
- In v2.11:
  - The grouping widget now works across multiple tbodies.
  - Added `group-false` header option which disables the grouping widget for a specific column.
  - Added the `group_collapsed` option - get more details in the options block below.
  - You can now toggle all group rows by holding down the shift key while clicking on a group header.
  - This widget now works properly with the pager addon (pager addon updated).
- Clicking on any of the sortable header cells will cause the column below it to sort and add a group header.

### Options

### Group widget default options (added inside of tablesorter `widgetOptions`)

- `group_collapsible` (`true`) - when `true`, the group headers become clickable and collapse the rows below it.
- `group_collapsed` (`false`) - when `true` and `group_collapsible` is also `true`, all groups will start collapsed (v2.11).
- `group_count` (`" ({num})"`) - allows you to add custom formatting, or remove, the group count within the group header. Set it to `false` or an empty string to remove the count.
- `group_callback` (`null`) - use this function to further modify the group header to include more information (i.e. group totals). Parameters include (`$cell, $rows, column, table`). See the example below for more details v2.12.
  - `$cell` - current group header table cell (jQuery object).
  - `$rows` - current group rows (jQuery object).
  - `column` - current table column being grouped (zero-based index).
  - `table` - current table (DOM).
- `group_complete` (`"groupingComplete"`) - event triggered on the table when the grouping widget has finished work v2.12.
- `group_formatter` (`null`) - use this function to modify the group header text before it gets applied. It provides various parameters (`txt, col, table, c, wo`) to make it work for any of the table columns and data. See the comments in the example below for more details.
  - `txt` - current text of the group header.
  - `col` - current table column being grouped (zero-based index).
  - `table` - current table (DOM).
  - `c` - table data from `table.config`.
  - `wo` - table widget options from `table.config.widgetOptions`.
- `group_separator` (`"-"`) - when the `group-separator` class name is added, it uses the setting from this option to split the table cell content for grouping v2.13.
- group date/time options - Name arrays included so that the language of the date groups can be modified easily. Defaults (English):
  - `group_months` (`[ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ]`) - Month names.
  - `group_week` (`[ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ]`) - Named days of the week.
  - `group_time` (`[ "AM", "PM" ]`) - Time of day.

### Header Class Names

### Group header class names (when changing the grouping, notice that the sort doesn't change, just the position and names of the group headers):

- `"group-word"` (same as `"group-word-1"`) - group the rows using the first word it finds in the column's parsed data.
- `"group-word-n"` (`"n"` can be any number) - group the rows using the nth word in the column*.
- `"group-separator"` (same as `"group-separator-1"`) - group the rows using the text between the start and first separator that it finds in the column's parsed data (v2.13).
- `"group-separator-n"` (`"n"` can be any number) - group the rows using the nth separated group in the column (v2.13)*.
- `"group-letter"` (same as `"group-letter-1"`) - group the rows using the first letter it finds in the column's parsed data.
- `"group-letter-n"` (`"n"` can be any number) - group the rows using letters 1 through n (if n = 2, then it's the first 2 letters) in the column's parsed data.
- `"group-number"` (same as `"group-number-1"`) - group the rows by the number it finds in the column (step of one).
- `"group-number-n"` (`"n"` can be any number) - group the rows into blocks of every n values. So, if n = 10, the groups will be 0-9, 10-19, 20-29, etc
- `"group-date"` - group the rows by full date (this shows the current UTC time corrected for your time zone)
- `"group-date-year"` - group the rows by year
- `"group-date-month"` - group the rows by month*
- `"group-date-day"` - group the rows by month/day*
- `"group-date-week"` - group the rows by day of the week*
- `"group-date-time"` - group the rows by time*
- `"group-false"` - disable grouping of rows for a column (v2.11).

* When sorting some columns, different group headers with the same group name may exist (try "group-date-week" and "group-date-time"). To make these columns sort specifically by the group you want, you'll need to modify the parser.

# Demo

Numeric column:
(includes subtotals)
Animals column:
Date column:

| Quality (number) | Numeric (every 10) | Priority (letter) | Animals (first letter) | Natural Sort (first word) | Inputs (second word) | Date (Full)
--- | --- | --- | --- | --- | --- | --- | ---
| Quality | Numeric | Priority | Animals | Natural Sort | Inputs | Date
| 1 | 10 |  | Koala | abc 123 |  | 1/13/2013 12:01 AM
| 3 | 29 |  | Kangaroo | abc 1 |  | 1/15/2013
| 2 | 10 |  | Ant | abc 9 |  | 1/13/2013
| 3 | 81 |  | Bee | zyx 24 |  | 1/11/2013
| 3 | 21 |  | Aardwolf | zyx 55 |  | 1/13/2013 03:30 AM
| 1 | 3 |  | Bear | abc 11 |  | 1/15/2013
| 4 | 12 |  | Armadillo | zyx 2 |  | 1/15/2013 12:30 PM
| 2 | 56 |  | Aardvark | abc 2 |  | 1/22/2013
| 1 | 55 |  | Lion | abc 9 |  | 2/15/2013
| 4 | 87 |  | Anteater | ABC 10 |  | 1/3/2013
| 2 | 98 |  | Lemur | zyx 1 |  | 1/11/2013
| 1 | 20 |  | Llama | zyx 12 |  | 12/13/2012

# Page Header

    <!-- Tablesorter: required -->
    <link rel="stylesheet" href="../css/theme.blue.css">
    <script src="../js/jquery.tablesorter.js"></script>

    <!-- Grouping widget -->
    <script src="../js/parsers/parser-input-select.js"></script>
    <script src="../js/widgets/widget-grouping.js"></script>

    <script>
    $(function(){

      $("table").tablesorter({
        theme : 'blue',
        headers: {
          0: { sorter: 'checkbox' },
          3: { sorter: 'select' },
          6: { sorter: 'inputs' }
        },
        widgets: ['group'],
        widgetOptions: {
          group_collapsible : true,       // make the group header clickable and collapse the rows below it.
          group_collapsed   : false,      // start with all groups collapsed
          group_count       : ' ({num})', // if not false, the "{num}" string is replaced with the number of rows in the group
          // change these default date names based on your language preferences
          group_months      : [ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' ],
          group_week        : [ 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday' ],
          group_time        : [ 'AM', 'PM' ],
          group_formatter   : function(txt, col, table, c, wo) {
            // txt = current text; col = current column
            // table = current table (DOM); c = table.config; wo = table.config.widgetOptions
            if (col === 7 && txt.indexOf('GMT') > 0) {
              // remove "GMT-0000 (xxxx Standard Time)" from the end of the full date
              txt = txt.substring(0, txt.indexOf('GMT'));
            }
            // If there are empty cells, name the group "Empty"
            return txt === "" ? "Empty" : txt;
          },
          // add a group total to the "Numeric" column
          group_callback    : function($cell, $rows, column, table){
            // callback allowing modification of the group header labels
            // $cell = current table cell (containing group header cells '.group-name' & '.group-count'
            // $rows = all of the table rows for the current group; table = current table (DOM)
            // column = current column being sorted/grouped
            if (column === 2) {
              var subtotal = 0;
              $rows.each(function(){
                subtotal += parseInt( $(this).find('td').eq(column).text() );
              });
              $cell.find('.group-count').append('; subtotal: ' + subtotal );
            }
          },
          // event triggered on the table when the grouping widget has finished work
          group_complete    : 'groupingComplete'
        }
      });

    });
    </script>

# CSS

# HTML