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 #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 igxHeadSelector let-headContext>
        <igx-checkbox
            [checked]="isChecked()" 
            [indeterminate]="isIndeterminate()" 
            (change)="handleHeadSelectionChange($event, headContext)">
        </igx-checkbox>
    </ng-template>
    <ng-template igxRowSelector let-rowContext>
        <igx-switch
            [checked]="rowContext.selected"
            (change)="handleRowSelection($event, rowContext.rowID)">
        </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.

igxRowSelector

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

Name	Type
index	property
rowID	property
selected	property

Index

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

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

rowID

rowID can be used to get a reference to the grid's row, this could be useful if you want to apply row-selection:

<ng-template igxRowSelector let-rowContext>
    <igx-switch
        [checked]="rowContext.selected"
        (change)="handleRowSelection($event, rowContext.rowID)">
    </igx-switch>
</ng-template>

In this example we pass in the context's rowID to a function which handles row-selection in the grid.

selected

selected 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 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 row's state.

igxHeadSelector

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

Name	Type
selectedCount	property
totalCount	property

The selectedCount property shows how many rows are currently selected.
The totalCount property shows how many rows are in the grid in total.

<ng-template igxHeadSelector let-headContext>
    <igx-checkbox
        [checked]="isChecked()" 
        [indeterminate]="isIndeterminate()" 
        (change)="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.

4. Assumptions and Limitations

deselecting all rows and toggling between select all and deselect all, resets the states of the header and row selector elements
in a hierarchical grid the child grids will inherit the head and row selectors from the root grid