# Row Grouping
## Live example
{% hint style="success" %}
[Row Grouping](https://demos.dikesoft.com/dk-grid/row/grouping) live example.
{% endhint %}
## Allowing the Row-Grouping operation
To allow the user to **group** the DkGrid rows, you must provide an input property named `allowRowGrouping`.
{% code title="row-grouping.component.html" %}
```markup
```
{% endcode %}
{% hint style="warning" %}
You can set the value of the `allowRowGrouping` property only at creation time.
{% endhint %}
After enabling the row-grouping operation, you will see a panel above the column headers. This panel is the **group panel**.
## Row Grouping through the UI
To allow the user to move columns to the **group panel**, you must provide an input property named `allowColumnDragging`. Then, mark the columns you want the DkGrid rows grouped by as **draggable** and **groupable**.
{% code title="row-grouping.component.html" %}
```markup
```
{% endcode %}
We have defined **Country**, **Age**, **Gender,** and **Name** columns as **draggable** and **groupable**.
{% hint style="info" %}
Remember, you should not **lock** a column if you want to **drag** that column.
{% endhint %}
Open the [Floating Configuration Panel](https://docs.dikesoft.com/overview#floating-configuration-panel) and mark the **Allow Column Dragging** checkbox.
Let us group the DkGrid rows by the **Country** and **Gender** columns.
### Custom templates
As discussed in the [Column Definitions](https://docs.dikesoft.com/columns/column-definitions#templates-for-displaying-field-values) section, every column has a **default template** for displaying the corresponding field value for every row.
Every group row will take the default template for displaying its value after grouping the rows. However, you can change the default template, as you can see in the following code snippet:
{% code title="row-grouping.component.html" %}
```markup
{{ value }}
{{ value }}
```
{% endcode %}
{% hint style="warning" %}
When defining a template to use in the group rendering, the related inner component will not pass the **row entry** object when calling the specified template.
{% endhint %}
After grouping the DkGrid rows by the **Country** and **Gender** columns, you will see the following output:
{% hint style="success" %}
We have defined a custom pipe named **countryFlag** to map the country name with its corresponding flag file.
{% endhint %}
### Clearing the group panel
You can remove columns from the group panel one by one or all of them in one action.
You can click on the **close icon** next to the column name to remove that column from the group panel. The action will **move** the column from the group panel to the **center panel**.
Or, you can remove all columns by clicking on the **group panel icon** at the left of the panel itself. The action will **move** all the columns from the group panel to the **center panel**.
## Group Selection
You can open the [Floating Configuration Panel](https://docs.dikesoft.com/overview#floating-configuration-panel) and click on the **Allow Selection** checkbox to enable selection.
{% hint style="success" %}
See the [Row Selection - Group Selection](https://docs.dikesoft.com/row-selection#group-selection) section for further details about group selection.
{% endhint %}
## Row Grouping using the API
You can use the **column API** to move columns to, from, or inside the group panel, and you can use the **rowGrouping API** to clear columns from the group panel.
{% hint style="info" %}
When you group the DkGrid rows by some columns, it is enough to define them as **draggable**, **groupable**, and not **locked** when using the **API**. Therefore, it does not matter if you do not provide the input property `allowColumnDragging`.
{% endhint %}
Before using the **API**, you must retrieve the corresponding DkGrid instance by querying the component's view.
{% tabs %}
{% tab title="row-grouping.component.html" %}
```markup
```
{% endtab %}
{% tab title="row-grouping.component.ts" %}
```typescript
@Component({
selector: 'row-grouping',
templateUrl: './row-grouping.component.html',
styleUrls: ['./row-grouping.component.scss'],
encapsulation: ViewEncapsulation.None,
changeDetection: ChangeDetectionStrategy.OnPush
})
export class RowGroupingComponent implements OnInit, OnDestroy {
// Retrieve the DikeGridComponent instance from the view:
@ViewChild('grid') dkGrid: DkGridComponent;
// ...
}
```
{% endtab %}
{% endtabs %}
{% hint style="success" %}
The **Row-Grouping API** is an instance of type `DkGridRowGrouping` under the [`DikeGridComponent`](https://docs.dikesoft.com/reference/components/dkgridcomponent) through the **read-only** property named `rowGrouping`.
{% endhint %}
The **rowGrouping API** has the following method:
| Method | Description |
| -------------------- | --------------------------------------------------------------------------- |
| `clearRowGrouping()` | This method will move all columns from the group panel to the center panel. |
{% hint style="success" %}
For further details, see the [`DikeGridRowGrouping`](https://docs.dikesoft.com/reference/dkgrid-api/dkgridrowgrouping) definition.
{% endhint %}
{% hint style="success" %}
For further details about the **column API**, see the [`DikeGridColumnDef`](https://docs.dikesoft.com/reference/dkgrid-api/dkgridcolumndef) definition.
{% endhint %}
To see the **API** in action, consider the following UI additions:
{% tabs %}
{% tab title="row-grouping.component.html" %}
```markup
```
{% endtab %}
{% tab title="row-grouping.component.ts" %}
```typescript
onGroupBy(): void {
if (this.columnControl.valid) {
const contentPanelColumn = this.columnControl.value as DikeColumnDef;
this.dikeGrid.columnDef.moveColumnIntoPanel(contentPanelColumn, 'groupPanel');
}
}
onMoveColumn(): void {
if (this.groupByColumnControl.valid) {
const groupPanelColumn = this.groupByColumnControl.value as DikeColumnDef;
this.dikeGrid.columnDef.moveColumnIntoPanel(groupPanelColumn, 'centerPanel');
}
}
onClearGroupPanel(): void {
this.dikeGrid.rowGrouping.clearRowGrouping();
}
```
{% endtab %}
{% endtabs %}
The previous HTML code generates the following output:
With the previous UI, you can do the following actions:
1. First, you can choose a column from the **Content panels** dropdown control. **Draggable**, **groupable**, and **not locked** columns have an icon indicating they can group the DikeGrid rows. After selecting a column, you can click on the **Group by** button, moving the column to the group panel.
2. The **Group panel** dropdown control contains the columns in the group panel. You can choose a column and move it to the center panel by clicking on the related button.
3. You can click on the **Clear group panel** button to move all the columns from the group panel to the center panel.
Be aware that we left all the columns from the content panels enabled, even the column group named **Complete Name**.
{% hint style="warning" %}
You cannot move column groups to the group panel from the UI. Nevertheless, you can use the **column API** to move column groups to the group panel. The column API takes all the data columns from the given column group and inserts those defined as **groupable**, **draggable**, and **not locked**.
{% endhint %}
It is essential to notice that we are **listening** to any change in the **DikeGrid's columns**, attaching a callback to the `contentPanelsColumnsChange` and `groupPanelColumnsChange` events.
{% tabs %}
{% tab title="row-grouping.component.html" %}
```markup
```
{% endtab %}
{% tab title="row-grouping.component.ts" %}
```typescript
onContentColumnsChange(columns: DikeColumnDef[]): void {
this.contentColumns = this.flatColumns(columns);
// Clear the selected column:
this.columnControl.patchValue(null);
}
onGroupColumnsChange(columns: DikeColumnDef[]): void {
this.groupColumns = this.flatColumns(columns);
// Clear the selected column:
this.groupByColumnControl.patchValue(null);
// Update the flag to let us know if the DikeGrid rows are grouped:
this.isDikeGridGroupedBy = columns.length > 0;
}
```
{% endtab %}
{% endtabs %}
Every time we receive a new set of columns, we flat them into a single array, invoking the method `flatColumns()`. So indeed, we are **flattening** the **column groups**, traversing them **recursively**.
{% code title="row-grouping.component.ts" %}
```typescript
private flatColumns(columns: DikeColumnDef[]): DikeColumnDef[] {
return columns.reduce((accum, column) => {
if (isDikeGroupColumnDef(column) && !!column.children && column.children.length > 0) {
return [ ...accum, column, ...this.flatColumns(column.children) ];
}
return [ ...accum, column ];
}, [ ]);
}
```
{% endcode %}
If you see the items of the **Content panels** **dropdown** control, you see the columns **Employee Id**, **Country**, **Complete Name**, **Name**, **Surname**, etc.
## Customizing the group panel
You can change the **group panel** **height**, the **height of the columns** displayed in the group panel, and the **Row-Grouping indent width**. Indeed, you can hide the Row-Grouping indent.
{% hint style="success" %}
For further details, see the [Grid Structure - Group panel section](https://docs.dikesoft.com/fundamentals/grid-structure/panels#group-panel).
{% endhint %}
You can open the [Floating Configuration Panel](https://docs.dikesoft.com/overview#floating-configuration-panel) for the **live demo** and change any mentioned properties.
## Empty values
When the DikeGrid instance groups the rows, the following values are considered empties:
| DikeColumnDataType | Values |
| ------------------- | --------------------------------------------------------------------------- |
| `Text` and `Binary` | `null`, `undefined`, and empty `strings`. |
| `Numeric` | `null`, `undefined`, and `NaN` values. |
| `Date` | `null`, `undefined`, and `Invalid Dates`. |
{% hint style="info" %}
We recommend you define the **getter function** for the columns you define. For further details, see the [Column Definitions](https://docs.dikesoft.com/columns/column-definitions#retrieving-and-updating-a-field-value) section.
{% endhint %}
## Row-Grouping events
Regarding row grouping operation, the DikeGrid instance emits the following events:
| Event | Description |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `groupPanelColumnsChange` | Every time the user moves a column to, from, and inside the group panel, this event emits. |
| `collapseGroupRowChange` | It emits when the user opens or closes a group row. |
We listen to these two events at the grid scope:
{% tabs %}
{% tab title="row-grouping.component.html" %}
```markup
```
{% endtab %}
{% tab title="row-grouping.component.ts" %}
```typescript
onGroupColumnsChange(columns: DikeColumnDef[]): void {
this.groupColumns = this.flatColumns(columns);
// Clear the selected column:
this.groupByColumnControl.patchValue(null);
// Update the flag to let us know if the DikeGrid rows are grouped:
this.isDikeGridGroupedBy = columns.length > 0;
}
onCollapseGroupRowChange(event: DikeGroupRowCollapseEvent): void {
console.log('DikeGroupRowCollapseEvent: ', event);
}
```
{% endtab %}
{% endtabs %}
{% hint style="success" %}
You can listen to these events from the [`DikeGridRowGrouping`](https://docs.dikesoft.com/reference/dkgrid-api/dkgridrowgrouping#events) instance.
{% endhint %}
{% hint style="success" %}
Please, open the **dev console** to see the output of the `collapseGroupRowChange` event.
{% endhint %}
## Summary
Firstly, you must allow the **Row-Grouping** operation at the grid scope by providing an input property named `allowRowGrouping`. Then, to group the DikeGrid rows by a column, you must define that column as **draggable**, **groupable**, and **not locked**.
For row grouping, through the **UI**, you must provide the input property named `allowColumnDragging`.
### Complete code for this section
{% tabs %}
{% tab title="row-grouping.component.html" %}
```markup