Improve this doc

Grouping

The grouping feature allows you to group rows together based on similar values in specific columns, providing an effect similar in some ways to an Excel pivot table. Columns that aren't grouped by can be aggregated, providing for example a running count of the number of rows in each group.

_** BREAKING CHANGES IN RC22 for grouping. Prior to RC22 grouping was a standalone feature, with RC22 a number of things have changed as grouping and treeView move to a shared code base. In particular:

Documentation for the grouping feature is provided in the api documentation, both under grouping itself, and shared functions in the treeBase documentation. In particular:

The tree structure itself is documented at treeBase.

Grouping can be set programmatically by using the columnDef option grouping: { groupPriority: 0 }, or for aggregations on a column by setting treeAggregation: {type: uiGridGroupingConstants.aggregation.COUNT}.

Optionally (and by default) grouped columns are moved to the front of the grid, which provides a more visually pleasing effect. In order to avoid creating a dependency on pinning, this is done by moving the columns themselves as part of the grouping feature, not through use of the pinning feature.

Grouping leverages the sort functionality, allowing a user to change the sort order or use external sort functionality and have the resulting list grouped. A column(s) that is marked as being grouped is always moved to the high order of the sort priority, as the data must be sorted to permit grouping.

Any grouped column has suppressRemoveSort set, when a column is ungrouped then suppressRemoveSort is returned to the value in the columnDef.

Grouping and aggregation should work cleanly with filtering - it should group and aggregate only the filtered rows.

Group header rows cannot be edited, and if using the selection feature, cannot be selected. They can, however, be exported.

The group rowHeader by default is always visible. If you'd like the groupRowHeader only present when at least one column is grouped then set the treeRowHeaderAlwaysVisible: false gridOption.

If you want to change the grouping programmatically after grid initialisation, you do this through calling the provided methods:

Grouping is still alpha, and under development, however it is included in the distribution files to allow people to start using it. Notable outstandings are:

Options to watch out for include:

If you would like to suppress the data in a grouped column (so it only shows in the groupHeader rows) this can be done by overriding the cellTemplate for any of the columns you allow grouping on as follows:

cellTemplate: '<div ng-if="!col.grouping || col.grouping.groupPriority === undefined || col.grouping.groupPriority === null || ( row.groupHeader && col.grouping.groupPriority === row.treeLevel )" class="ui-grid-cell-contents" title="TOOLTIP">{{COL_FIELD CUSTOM_FILTERS}}</div>'

In the example below this has been done on the state column only. This isn't included in the base code as it could potentially interact with people's custom templates.

Tuning the way aggregations work can be done through defining a columnsProcessor that runs with higher (later) priority than the groupingColumnProcessor (so higher than 400), and that looks for grouped or aggregated columns and changes things like the treeAggregationFn, or the customTreeAggregationFinalizerFn. See tutorial 320 for an example.

For better performance with the following example, you can choose to load the ui-grid.core.js and specific feature files instead: 

  <script src="/release/ui-grid.core.min.js"></script>
  <script src="/release/ui-grid.tree-base.min.js"></script>
  <script src="/release/ui-grid.grouping.min.js"></script>

Example

In this example we group by the state column then the gender column, and we count the names (a proxy for counting the number of rows), we find the max age for each grouping, and we calculate the average balance. We suppress the aggregation text on the balance column because we want to format as currency...but that means that we can't easily see that it's an average.

We write a function that extracts the aggregated data for states and genders (if you change the grouping then this function will stop working), and writes them to the console.

Source



























Demo