Row Selection Templating (Grid feature)

Row Selection Templating Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. Assumptions and Limitations
5. References

1. Overview

A user should be able to template the default checkbox elements that are used 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 element and in the grid's header.

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

2. User Stories

As an end user, I want to:

• 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 apply styling accordingly

3. Functionality

With the igx-grid row selection, you can bind to the row's and header's 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
onCheckBoxClick	method
isSelected	property

Index

index can be used to access the rows' indexes:

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

onCheckBoxClick

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

<ng-template igxSelectionRow let-rowContext>
     <igx-switch (change)="rowContext.onCheckboxClick($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.

NOTE: onCheckboxClick should be refactored to be a generic function that handles row selection for any template, it is not meant to handle only checkbox clicks.

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 besides 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 grid icon's header context and access the following members:

Name	Type
onHeaderCheckboxClick	method

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

Here we bind the onHeaderCheckboxClick 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.

NOTE: The onHeaderCheckboxClick function should be refactored to be a generic function that handles row selection for any template, it is not meant to handle only checkbox clicks.

4. Assumptions and Limitations

5. References

Custom template for selection checkbox issue.