Row Selection Templating (Grid feature)

Row Selection Templating Specification

1. Overview

A user should be able to template the default selector elements in the igx-grid.

Objectives

The igx-grid should provide API for templating any element as an entity that handles row-selection both in the grid's row elements and in the grid's header. If grouping is enabled an API for templating the grid’s groupByRow checkbox selectors should be provided as well.

<igx-grid #grid [data]="gridData" [primaryKey]="'CompanyID'" [rowSelection]="'multiple'">
    <igx-column [field]="'CompanyID'"></igx-column>
    <igx-column [field]="'CompanyName'"></igx-column>
    <igx-column [field]="'Country'" [groupable]="true"></igx-column>
    <igx-column [field]="'City'" [groupable]="true"></igx-column>
    <ng-template igxHeadSelector let-headContext>
        <igx-checkbox
            [checked]="isChecked(headContext)"
            [indeterminate]="isIndeterminate(headContext)">
        </igx-checkbox>
    </ng-template>
    <ng-template igxRowSelector let-rowContext>
        <igx-switch
            [checked]="rowContext.selected">
        </igx-switch>
    </ng-template>
    <ng-template igxGroupRowSelector let-context>
        <igx-checkbox
            [checked]="context.selectedCount > 0 && context.selectedCount === context.totalCount"
            [indeterminate]="context.selectedCount > 0 && context.selectedCount < context.totalCount">
        </igx-checkbox>
    </ng-template>
</igx-grid>

2. User Stories

As an end user, I want to:

be able to determine if the current row is selected or not
be able to determine the index of the data record for the current row
be able to select a row using the grid's row-selection element
be able to deselect a row using the grid's row-selection element
be able to select all rows using the grid's header selection element
be able to deselect all rows using the grid's header selection element
be able to select all rows in a group using the grid's groupBy-row-selection element
be able to deselect all rows in a group using the grid's groupBy-row-selection element

Developer Stories

As a developer, I want to:

be able to template the grid's row selection element
be able to template the grid's header selection element
be able to template the grid's groupBy-row selection element
be able to handle the states of the grid's row selection element
be able to handle the states of the grid's header selection element
be able to handle the states of the grid's groupBy-row selection element

3. Functionality

With the grid's row-selection, you can bind to the rows', headers' and groupBy-rows' contexts and use the members that they expose.

igxRowSelector

With the igxRowSelector directive you can bind to the grid's row context and access the following members:

Name	Type
index	property
rowID	property
selected	property
select	method
deselect	method

Index

index can be used to access the indices of data records for related rows:

<ng-template igxRowSelector let-rowContext>
    {{ rowContext.index }}
</ng-template>

rowID

rowID can be used to get a reference of a grid's row, this is useful when you implement a click handler on the row selector element:

<ng-template igxRowSelector let-rowContext>
    <igx-checkbox (click)="onSelectorClick($event, rowContext.rowID)">
    </igx-checkbox>
</ng-template>

By default, the grid will handle all row-selection when the click is registered on the row itself or on the row selector's container. Handling click events on the selector should be implemented by the developer.

selected

selected is a boolean property that shows whether the current row is selected or not.

<ng-template>
     <ng-template igxRowSelector let-rowContext>
        <igx-switch 
            [checked]="rowContext.selected">
        </igx-switch>
    </ng-template>
</ng-template>

In the above example we are using an igx-switch and we bind the rowContext.selected property to the switch's checked property. By doing so, we ensure that every time we select the row, the switch will also update its state and will be either selected or deselected depending on the current row's state.

select

The select method allows you to set the state of a single row, in a hierarchical grid, to selected.

<ng-template igxRowSelector let-rowContext>
    <igx-switch 
        [checked]="rowContext.selected"
        (click)="rowContext.select()">
    </igx-switch>
</ng-template>

The select method is exposed in the row context of a hierarchical grid to make it easier for a developer to implement a click handler on the row selector.

deselect

The deselect method allows you to set the state of a single row, in a hierarchical grid, to not selected.

<ng-template igxRowSelector let-rowContext>
    <igx-switch 
        [checked]="rowContext.selected"
        (click)="rowContext.deselect()">
    </igx-switch>
</ng-template>

Similar to the select method, the deselect method is available only in the igx-hierarchical-grid and provides an easy way to deselect a row by binding to the click event of the row selector.

The select and deselect methods, of a row context, know which level of the hierarchy they are being called in.

igxHeadSelector

With the igxHeadSelector directive you can bind to the grid's header context and access the following members:

Name	Type
selectedCount	property
totalCount	property
selectAll	method
deselectAll	method

selectedCount

The selectedCount property shows how many rows are currently selected.

<ng-template igxHeadSelector let-headContext>
    {{ headContext.selectedCount }}
</ng-template>

totalCount

The totalCount property shows how many rows are there in the grid in total.

<ng-template igxHeadSelector let-headContext>
    {{ headContext.totalCount }}
</ng-template>

selectAll

The selectAll method sets the states of all rows, in a hierarchical grid, to selected.

<ng-template igxHeadSelector let-headContext>
    <igx-switch 
        (click)="headContext.selectAll()">
    </igx-switch>
</ng-template>

The selectAll method is exposed in the header context of a hierarchical grid to make it easier for a developer to implement a click handler on the header selector.

deselectAll

The deselectAll method sets the states of all rows, in a hierarchical grid, to not selected.

<ng-template igxHeadSelector let-headContext>
    <igx-switch 
        (click)="headContext.deselectAll()">
    </igx-switch>
</ng-template>

Similar to the selectAll method, the deselectAll method is available only in the igx-hierarchical-grid and provides an easy way to deselect all rows by binding to the click event of the header selector.

The selectAll and deselectAll methods, of a header context, know which level of the hierarchy they are being called in.

<ng-template igxHeadSelector let-headContext>
    <igx-checkbox
        [checked]="isChecked(headContext)"
        [indeterminate]="isIndeterminate(headContext)"
        (click)="handleHeadSelectionChange($event, headContext)">
    </igx-checkbox>
</ng-template>

Here we use the igxHeadSelector directive to template the grid's head selector to be an igx-checkbox element. In the headContext we have the selectedCount and the totalCount properties which can be used to determine the state of the head selector.

igxGroupByRowSelector

With the igxGroupByRowSelector directive you can bind to the grid's groupBy row context and access the following members:

Name	Type
selectedCount	property
totalCount	property
groupRow	property

selectedCount

The selectedCount property shows how many of the group records are currently selected.

<ng-template igxGroupByRowSelector let-groupByRowContext>
    {{ groupByRowContext.selectedCount }}
</ng-template>

totalCount

The totalCount property shows how many records belong to the group.

<ng-template igxGroupByRowSelector let-groupByRowContext>
    {{ groupByRowContext.totalCount }}
</ng-template>

groupRow

The groupRow property returns a reference to the group row.

<ng-template igxGroupByRowSelector let-groupByRowContext>
    <div (click)="handleGroupByRowSelectorClick($event, groupByRowContext.groupRow)">Handle groupRow</div>
</ng-template>

example

<ng-template igxGroupByRowSelector let-groupByRowContext>
    <igx-checkbox
        [checked]="groupByRowContext.selectedCount > 0 && groupByRowContext.selectedCount === groupByRowContext.totalCount"
        [indeterminate]="groupByRowContext.selectedCount > 0 && groupByRowContext.selectedCount < groupByRowContext.totalCount"
        (click)="handleGroupByRowSelectorClick($event, groupByRowContext)">
    </igx-checkbox>
</ng-template>

Here we use the igxGroupByRowSelector directive to template the grid's groupBy row selector to be an igx-checkbox element. In the groupByRowContext we have the selectedCount and the totalCount properties. They can be used to determine the state of the group row selector. The groupRow property returns a reference to the current group row.