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 HTML element as an entity that handles row-selection both in the grid's row elements and in the grid's header.

<igx-grid [data]="gridData" [primaryKey]="'ProductID'" 
    [rowSelectable]="true" (onRowSelectionChange)="handleRowSelection($event)">
    <igx-column [field]="'ProductID'" [editable]="true"></igx-column>
    <igx-column [field]="'ProductName'"></igx-column>
    <igx-column [field]="'UnitsInStock'"></igx-column>
     <ng-template igxSelectionHeader let-headContext>
        <igx-switch (change)="headContext.onSelectionsChange($event)"></igx-switch>
    </ng-template>
    <ng-template igxSelectionRow let-rowContext>
        <igx-switch [checked]="rowContext.isSelected" (change)="rowContext.onSelectionChange($event)"></igx-switch>
    </ng-template>
</igx-grid>

2. User Stories

As an end user, I want to:

be able to determine if the current row is selected
be able to determine the index of the data record for the current row
be able to select a row using a row-selection element in the grid's rows
be able to deselect a row using a row-selection element in the grid's rows
be able to select all rows using the header selection element in the grid
be able to deselect all rows using the header selection element in the grid
be able to click anywhere in the row-selection area of the grid's row and select a concrete row
be able to click anywhere in the row-selection area of the grid's row and deselect a concrete row
be able to click anywhere in the row-selection area of the grid's header selection element and select all of the grid's rows
be able to click anywhere in the row-selection area of the grid's header selection element and deselect all of the grid's rows

Developer Stories

As a developer, I want to:

be able to template the selection element of the grid's rows
be able to template the grid's header selection element
be able to handle the rows' states and to style said rows accordingly

3. Functionality

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

igxSelectionRow

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

Name	Type
index	property
onSelectionChange	method
isSelected	property

Index

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

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

onSelectionChange

onSelectionChange is used to apply selection onto the currently selected row:

<ng-template igxSelectionRow let-rowContext>
     <igx-switch (change)="rowContext.onSelectionChange($event)"></igx-switch>
</ng-template>

Binding this method to a change event, for instance, will make sure that every time the igx-switch changes its state, the current row will be selected.

isSelected

isSelected is a property that allows you to define your own logic on what to do when a row is selected, this could be a change of styling, for example, or anything that would signal the end user that a row has been selected.

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

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

igxSelectionHeader

With the igxSelectionHeader directive you can bind to the header-icon's context and access the following members:

Name	Type
onSelectionsChange	method

<ng-template igxSelectionHeader let-headContext>
    <igx-switch (change)="headContext.onSelectionsChange($event)"></igx-switch>
</ng-template>

Here we bind the onSelectionsChange method to the change event of an igx-switch. And the igxSelectionHeader directive ensures that this is applied to the grid's header template. By binding it like this, we ensure that every time the igx-switch changes its state, all of the grid's rows will have their selection states changed. A good thing to note is that when a row has its selection state changed, the row's isSelected property changes and since we pass this to the row's context, you can bind to that change and handle it. See isSelected.