group

Optional. Enables grouping row data by column values and allows configuring grouping settings

pro version only

The described functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.

info

Note that when you initialize Grid with the group configuration property, the tree-like mode is enabled for Grid and it will have the type: tree property in its configuration.

Usage

type TAggregate = "sum" | "count" | "min" | "max" | "avg" | string;

interface IGroupOrder {
    by: string | ((row: IRow) => string);
    map?: { [field: string]: [string, TAggregate] | ((row: IRow[]) => string | number) };
    summary?: "top" | "bottom";
}

type IGroupOrderItem = string | IGroupOrder | ((row: IRow) => string);

interface IGroup {
    panel?: boolean; // true by default
    panelHeight: number; // 40 by default
    hideableColumns?: boolean; // true by default
    showMissed?: boolean | string; // true by default
    showEmptyGroups?: boolean; // false by default
    counter?: boolean | ((row: IRow) => string); // true by default
    fields?: { [colId: string]: IGroupOrder };
    order?: IGroupOrderItem[];
    column?: string | ICol;
}

interface IGridConfig {
    ...
    group?: boolean | IGroup;
    ...
}

Parameters

As an object the group configuration option has the following properties:

tip

You can find the detailed description of the group object properties with examples in the related guide Grouping data.

• panel - (optional) enables the group panel, true by default. When the panel config is set to true, a user can drag columns' headers to the panel of creating and modifying groups
• panelHeight - (optional) defines the height of the group panel in pixels, which allows adjusting the space for rendering a group of columns, 40 by default
• hideableColumns - (optional) specifies whether columns will be hidden on a group creation, true by default. If set to false, columns used for grouping will remain visible
• showMissed - (optional) controls visibility of the elements that don't suit the grouping criteria (e.g. data without values), true by default
  • if set to true, the rows that don't have values for grouping are rendered row by row after all the data
  • if a string value is set, e.g. "Missed", the rows that don't have values for grouping are rendered as a separate group the name of which will have the specified string value. This group will be rendered as the last one
  • if set to false, the rows that don't suit the grouping criteria won't be rendered
• showEmptyGroups - (optional) specifies whether a group that loses all its rows stays in the grid, false by default
  • if set to false, such a group leaves the view together with its summary row and its nested groups. resetFilter() brings back a group emptied by filtering, while a group emptied by remove() leaves the grid for good
  • if set to true, such a group remains visible with the $count: 0 value and emptied aggregates: the "sum" and "count" aggregations give 0, while "avg", "min" and "max" give null, as described in the Data calculation functions guide
• counter - (optional) defines the text rendered next to the group name in the column with grouped data, true by default
  • if set to true, Grid renders the current number of rows of the group in brackets, e.g. (2)
  • if set to false, Grid renders only the group name
  • if set to a function, Grid calls it with the group header row, and the function returns the string to render. Grid inserts the returned value as HTML, so it may contain markup; an empty string renders no counter. The row gives access to the $count, $totalCount and $by service properties and to every aggregated field of the map object of the level
• fields - (optional) predefines an extended configuration for data grouping by certain columns, by setting the rules of aggregation and rendering of the results. The attributes of the fields object correspond to the ids of columns for which the aggregation rules and the order of results are being configured. The configuration of a column is defined by the IGroupOrder object that has the following properties:
  • map - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be:
    • a tuple [string, TAggregate] that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the dhx.methods helper
    • a user-defined aggregation function ((row: IRow[]) => string | number)
  • summary - (optional) specifies where the total row is rendered - at the top or at the bottom of the group
• order - (optional) defines the order of grouping by setting the sequence of columns for grouping. The elements of the order array can be:
  • a string that represents a grouping field
  • a function ((row: IRow) => string) for dynamic defining of a group
  • an IGroupOrder object that has the following properties:
    • by - the field name or a function ((row: IRow) => string) for user-defined grouping
    • map - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be:
      • a tuple [string, TAggregate] that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the dhx.methods helper
      • a user-defined aggregation function ((row: IRow[]) => string | number)
    • summary - (optional) specifies where the total row is rendered - at the top or at the bottom of the group
• column - (optional) defines the configuration of a column that renders values of the grouped data. This column will be used as a main one for structuring and rendering data grouped by value

Example

const grid = new dhx.Grid("grid_container", {
    columns: [
        { id: "country", header: [{ text: "Country" }], groupable: true },
        { id: "population", header: [{ text: "Population" }] },
        { id: "area", header: [{ text: "Land Area (Km²)" }] }
    ],
    group: {
        panel: true
    },
    data: dataset
});

Related article: Grouping data

Related sample: Grid. Group counter after filtering

Change log:

• The counter and showEmptyGroups properties are added in v9.4
• Added in v9.0