The Grid component supports grouping data by one or several column values. Use the corresponding plugins or UI (Group Panel and column headers) to manage the grouping state and group data programmatically.
The following plugins implement grouping features:
- GroupingState - controls the grouping state
- IntegratedGrouping - performs built-in data grouping
- CustomGrouping - converts custom formatted grouped data to a supported format
- TableGroupRow - renders group rows
- TableHeaderRow - renders the header row and implements column dragging
- Toolbar - renders the Grid Toolbar
- GroupingPanel - renders the Group Panel
Note that plugin order is important.
Basic Setup
Use the GroupingState
, IntegratedGrouping
(or CustomGrouping
) and TableGroupRow
plugins to set up a Grid with simple static grouping.
In the following examples, the grouping options are specified using the GroupingState
plugin's grouping
property, which is usual for the controlled mode. However, the onGroupingChange
event handler is not specified because the grouping option is not supposed to be changed internally as the grouping UI is not available.
Built-in Grouping
In the following example, the data is specified as plain rows. In this case, the data should be grouped using the IntegratedGrouping
plugin.
Custom Grouping
Use the CustomGrouping
plugin if the data has a hierarchical structure (already grouped).
In the following example, the data is specified as an array of groups. Specify the CustomGrouping
plugin's getChildGroups
property to parse a custom group structure.
Configure the Grouping UI
Use the Toolbar
, GroupingPanel
and TableHeaderRow
plugins in addition to those used for the basic setup to enable the grouping UI. You can configure the UI to provide any of the following methods for specifying grouping options:
- Drag a column header to or from the Group PanelImport the DragDropProvider plugin.
- Use the corresponding button in a header cellAssign true to the
TableHeaderRow
plugin'sshowGroupingControls
and theGroupingPanel
plugin'sshowGroupingControls
properties.
You can also set the GroupingPanel
plugin's showSortingControls
option to true to enable sorting data by a grouped column.
In the following example, the Grid functions are in the uncontrolled mode. This means that the Grid controls its grouping state internally. The initial grouping options are specified in the GroupingState
plugin's defaultGrouping
property.
Controlled Mode
In controlled mode, pass a grouping options array to the GroupingState
plugin's grouping
property and handle the onGroupingChange
event to control the grid grouping state.
Disable Grouping by a Column
You can disable grouping/ungrouping for a specific column using the GroupingState plugin's columnExtensions
property.
Built-in Grouping with Custom Values
Pass a grouping criterion function to the IntegratedGrouping
plugin’s columnExtensions property to group data by a custom key based on the specified column's value. Set the columns configuration's showWhenGrouped
field to true to avoid hiding the column when data is grouped by this column. In the following example, data is grouped by the first letter of the "city" column's values while still displaying the column.
You can also assign a Boolean value to the TableGroupRow
plugin's showColumnsWhenGrouped
property to define what columns should remain visible when they group data.
Note that if the grouping criterion function returns a non-primitive value, you should also specify a custom group cell template using the TableGroupRow
plugin's cellComponent
property as demonstrated in the following example:
Remote Grouping
You can perform remote grouping by handling grouping state changes, generating a request based on the grouping state and sending it to a server that can return grouped data.
Grouping options are updated whenever an end-user interacts with the grouping UI. Handle grouping option changes using the GroupingState
plugin's onGroupingChange
and onExpandedGroupsChange
events and request data from the server using the newly applied grouping options.
Use the CustomGrouping
plugin instead of the IntegratedGrouping
plugin for remote grouping.
While waiting for a response from a server, there is a moment when the grouping state does not match the data in the Grid
's rows
property. To avoid issues, temporarily assign the grouping
and expandedGroups
state fields' "old" values to the properties with the same names in the GroupingState
plugin. This means configuration changes are not applied to the Grid
immediately. Once the grouped data is received from the server, pass it to the Grid
component's rows
property and reset the CustomGrouping
plugin's grouping
and expandedGroups
property values (set them to null
). At this point, the Grid
simultaneously applies the changes to its grouping configuration and receives the updated data set.
The following example demonstrates remote grouping with local expanding/collapsing, and the approach described in the previous paragraph:
Browser Support Notes
In Safari, the virtual table is scrolled when a user drags a column header. This is caused by a bug in WebKit: Unable to call event.preventDefault in dynamically added event listener.