Grouping Data
Overview
You can group rows together that share a column value, this creates a visible header for each group and allows the user to collapse groups that they don't want to see.
Setup
Grouping by Field
Rows can be grouped by a common field value by setting the groupBy option to the name of the field to be grouped.
groupBy:"gender",
If you need to group by more complex value, you can pass a function that returns a string that represents the group.
groupBy:function(data){
//data - the data object for the row being grouped
return data.gender + " - " + data.age; //groups by data and age
}
Custom Group Headers
You can set the contents of the group headers with the groupHeader option. This should return the contents of the group header.
groupHeader:function(value, count, data, group){
//value - the value all members of this group share
//count - the number of rows in this group
//data - an array of all the row data objects in this group
//group - the group component for the group
return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
},
Group Open State
You can set the default open state of groups using the groupStartOpen property.
groupStartOpen:true,
This can take one of three possible values:
- true - all groups start open (default value)
- false - all groups start closed
- function() - a callback to decide if a group should start open or closed
Group Open Function
If you want to decide on a group by group basis which should start open or closed then you can pass a function to the groupStartOpen property. This should return true if the group should start open or false if the group should start closed.
groupStartOpen:function(value, count, data, group){
//value - the value all members of this group share
//count - the number of rows in this group
//data - an array of all the row data objects in this group
//group - the group component for the group
return count > 3; //all groups with more than three rows start open, any with three or less start closed
},
Group Toggle Element
By default Tabulator allows users to toggle a group open or closed by clicking on the arrow icon in the left of the group header. If you would prefer a different behaviour you can use the groupToggleElement option to choose a different option:
var table = new Tabulator("#example-table", {
groupToggleElement:"header", //toggle group on click anywhere in the group header
});
The option can take one of three values:
- arrow - togggle group on arrow element click
- header - toggle group on click anywhere on the group header element
- false - prevent clicking anywhere in the group toggling the group
Multi Level Grouping
To set multiple levels of grouping, pass an array to the groupBy option. Each item in the array will be a sub-group of the previous item.
groupBy:["gender", "color"], //group by gender then favourite color
To then set the default open state of each of these levels you can pass an array to the groupStartOpen option.
groupStartOpen:[true, false], //start with gender groups open and color sub groups closed
You can also set a different header for each level of group, as above you pass an array to the groupHeader option.
groupHeader:[
function(value, count, data){ //generate header contents for gender groups
return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
},
function(value, count, data){ //generate header contents for color groups
return value + "<span style='color:#0dd; margin-left:10px;'>(" + count + " item)</span>";
},
],
Sub Group Styling
Each group header element is assigned a class based on its level in the grouping list. This allows you to differentiate between different gouping levels by styling their classes. By default each level's headers are indented more than the last.
For example, all group headers in the first grouping level will be assigned the class tabulator-group-level-1
Note: You can have as many levels of subgroup as you like, but Tabulator only comes with indent styling built in for the first five levels of subgroup.
Group Management
If you want to alter the structure of the groups after the table has been created there are a number of functions available.
Change the GroupBy Fields
You can use the setGroupBy function to change the fields that rows are grouped by. This function has one argument and takes the same values as passed to the groupBy setup option.
table.setGroupBy("gender");
Change the Start Open States
You can use the setGroupStartOpen function to change the default open state of groups. This function has one argument and takes the same values as passed to the groupStartOpen setup option.
table.setGroupStartOpen(true);
Change the Header Formatter
You can use the setGroupHeader function to change the header generation function for each group. This function has one argument and takes the same values as passed to the groupHeader setup option.
table.setGroupHeader(function(value, count, data, group){
//value - the value all members of this group share
//count - the number of rows in this group
//data - an array of all the row data objects in this group
//group - the group component for the group
return value + " (" + count + " items)" ; //return the header contents
});
Note: If you use the setGroupStartOpen or setGroupHeader before you have set any groups on the table, the table will not update until the setGroupBy function is called.
Get Group Components
You can use the getGroups function to retrieve an array of all the first level Group Components in the table.
var groups = table.getGroups();
Movable Rows and Grouping
If you move a row between groups, its values will be updated to match those of the new group.
If you move or delete the last row in a group out of that group, that group will be removed.
Callbacks
A range of callbacks are available for grouping. See the Group Callbacks section for more information.