Column Grouping Overview (igGrid)

Topic Overview

Purpose

This topic introduces the grouping functionality of the igGrid™.

In this topic

This topic contains the following sections:

• Introduction
• GroupBy Persistence
• Grouping Features Overview
• API Usage
• Keyboard Interactions
• Related Content

Introduction

The igGrid supports a column grouping functionality that enables the user to employ the data in one or more columns in a grid as a primary and, respectively, secondary criteria for organizing the records in the group in groups. The picture bellow demonstrate a grid in which the values of the SafetyStockLevel column – 500, 8000, 1,000, etc. – are used to group and arrange the data in the grid, i.e. the grid is grouped by its SafetyStockLevel column.

Grouping in the igGrid works the same as the analogous functionality in Microsoft® Office Outlook® – you drag a column that you want to group by and drop it into a special grouping area above the grid. This re-arranges the grid with as many groups as distinct value are there in the selected column. In addition, inside the groups, the records are sorted. If you drop additional columns, then, within the already existing groups, further groupings are applied.

You can define your own custom grouping method. For details about custom grouping, refer to the Grid Group By Overview topic.

Grouping is implemented and managed by the Group By widget.

GroupBy Persistence

Persisting grouped columns between igGrid re-bindings is made easy in version 14.1 and in fact replaces the previous default behavior.

Note GroupBy persistence is true by default. This is a breaking change.

When you enable igGridGroupBy you are already using it in a persist mode. This means that after explicitly calls of dataBind(), that persistence is applied for UI and data source view (the grouped columns are not cleared and the data source remains sorted)

GroupBy persistence is implemented for igHierarchicalGrid too.

The following sample demonstrates the persistance capabilities of the GroupBy feature.

If you would like to retain the previous behavior of group by being cleared after user re-binds the igGrid, you can do this by disabling the feature through the persist option as shown in the code snippet below:

In JavaScript:

features: [
  { 
     name: “GroupBy”, 
     persist: false 
  }
]

Grouping Features Overview

The table below briefly explains the grouping main features and the Group By widget properties that manage them.

Note: In the following table, the properties and events specific to the Group By Dialog are not listed. They are available in the Group By Dialog topic.

The following sample demonstrates how to use the compareFunc to customize the grouping:

Note: You can also customize grouping of the time column using the compareFunc. See the example code for more details.

API Usage

In order to group a column programmatically, you need to do this in the following way:

In JavaScript:

$('#grid1').igGridGroupBy('groupByColumn', 'ProductID');

The applied sorting expressions can be retrieved from the data source of the grid. In order to get them programmatically, you can use the following:

In JavaScript:

var expressions = $('#grid1').data('igGrid').dataSource.settings.sorting.expressions; // array of expressions
// expression structure
{compareFunc: <type="function" comparer function>, dir: <type="string" sort direction>, fieldName: <type="string" column key>, isGroupBy: <type="bool" is the expression created by the Group By widget>, layout: <type="string" the key of the layout if done in igHierarchicalGrid>}

Expressions created by the Group By widget have a property "isGroupBy" equals to "true" to distinguish them from the ones created by the Sorting widget.

To get the grouped data (data rows and group rows) programmatically you need to do this:

In JavaScript:

var data = $('#grid1').data('igGrid').dataSource.groupByData();
// group rows' structure
{collapsed: <type="bool" collapsed state>, fieldName: <type="string" column key>, gbExpr: <type="object" group by expression object>, id: <type="string" identificator of the group row>, len: <type="number" the number of data rows in the group>, level: <type="number" level of grouping>, recs: <type="array" set of the data records in the group>, val: <type="string" the value of the group>}

The group rows in the group by data are objects which contain the generated ID of the physical group row. The ID can be used to collapse and expand the row programmatically:

In JavaScript:

var data = $('#grid1').data('igGrid').dataSource.groupByData(), 
    id = data[0].id; 
// collapse
$('#grid1').igGridGroupBy("collapse", id); 
// expand
$('#grid1').igGridGroupBy("expand", id);

The following sample provides additional information related to the API usage:

Keyboard Interactions

The following keyboard interactions are available.

When focus is on the grid:

• TAB: Can move focus between the focusable elements of the GroupBy feature: the select columns link in the GroupBy area.

When focus is on the element:

• ENTER: Opens the GroupBy dialog.

When focus is on the dialog:

• TAB: Moves focus between the focusable elements of the dialog – “Group By” buttons, “Clear all” buttons, “Apply” and “Cancel” buttons. The related actions can be applied by hitting ENTER while the focus is on the related element.
• ESCAPE: Closes the dialog.

Related Content

Topics

The following topics provide additional information related to this topic.

• Enabling Column Grouping (igGrid)

• Grid Group By Properties Reference

• Grid Known Issues and Breaking Changes

Samples

The following samples provide additional information related to this topic.

• GroupBy