# 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.14, added
  - `group_dateString` option which is a function that allows you to format the date string when using the `group-date` header class name. This is the default function:

        group_dateString  : function(date) { return date.toLocaleString(); }

    Other functions that can be used are `date` (alone), `date.toLocaleString()`, `date.toLocaleDateString()` or `d.toLocaleTimeString()`. See this reference for more details.
- 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 href="../css/theme.blue.css" rel="stylesheet">
    <script src="../js/jquery.tablesorter.js"></script>
    <script src="../js/jquery.tablesorter.widgets.js"></script>

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

# Script

# CSS

# HTML