dxDataGrid provides you with the capability to group grid records by values of a single or multiple columns. When grouping is applied, records with identical values in the same column or several columns are combined into one or several corresponding groups. Visually, groups are separated one from another by a group row containing a grouping value. This topic gathers information about settings that define user-specified grouping and methods that can be used to apply grouping in code.
Groups in a grid are always sorted even if sorting was not applied to a column used in grouping before it was moved to the group panel. By default, groups are sorted in ascending order. To change this, a user must click the header of the grouping column.
NOTE: When moving a column back from the group panel, its resulting location depends on the allowColumnReordering option. If this option is true, the column will be placed exactly where its header is dropped. If false, the column will have a location according to the order of columns in the columns array.
Grouping in UI
To enable grouping in the UI, simply make the group panel visible using the groupPanel | visible option. If this feature is not required, hide the group panel using the same option or disallow column dragging for the group panel using the groupPanel | allowColumnDragging option.
For more information on configurable features of the group panel, refer to the Group Panel topic.
Additionally, individual columns can be prevented from being used in grouping. For these columns, the allowGrouping option must be set to false.
Grouping in Code
If required, you can apply grouping in code. For this purpose, assign an integer number to the groupIndex option of the required column using the columnOption method. To ungroup records, assign undefined to this option using the same method. To clear grouping settings of all columns, call the clearGrouping() method as shown in the code snippet below.
Calculating the Group Index
A group index is an integer number greater or equal to 0 that indicates the grouping order. The group index is used when specifying an initial grouping order or expanding/collapsing groups in code. Columns that are not used in grouping have the undefined group index. The following image illustrates how to calculate the group index.
Expanding and Collapsing Groups
Groups can be either expanded or collapsed. When expanded, a group is represented by a group row and data rows matching the grouping value. When collapsed, a group is represented by a group row only.
For more information about group rows, refer to the Group Rows topic.
Groups in a grid may appear expanded or collapsed initially. To specify this for all groups, use the autoExpandAll option of the grouping object. If you need to specify this setting for an individual column, use the autoExpandGroup option of this column.
To expand or collapse a group, a user must click the arrow accompanying its group row, or press ENTER when the group row is in focus.
The same operation can be performed in code by calling the expandAll(groupIndex) and collapseAll(groupIndex) methods. To discover how to calculate the group index, which is passed to these methods, refer to the Calculating the Group Index subtopic. Calling these methods without argument expands/collapses all groups.
Setting Initial Grouping
Grouping can be applied not only at runtime, but also at design time. To do this, assign an integer value to the groupIndex option of those columns that must be used in grouping. Note that grouping order is based on those values. For information about calculating the group index, see the Calculating the Group Index subtopic.
Additionally, you can make the initially set grouping invariable. For this purpose, assign false to the allowGrouping option of the columns used in grouping. In this case, make the group panel visible, but block it by assigning false to the groupPanel | allowColumnDragging option. Thus, a user is notified about the applied grouping, but cannot change it.