Row Selection (Grid feature)

Row Selection Specification

Revision History

Version	User	Date	Notes
0.1	Nikolay Alipiev	March 22, 2018	Initial Draft
0.2	Nikolay Alipiev	March 27, 2018	API Renaming
0.3	Nikolay Alipiev	April 2, 2018	API Update (methods, events); add user stories for header checkbox; add other features integration paragraph;
0.4	Nikolay Alipiev	April 3, 2018	Add user stories
0.5	Nikolay Alipiev	April 4, 2018	Add keyboard navigation; onRowEditing event args;
0.6	Nikolay Alipiev	April 4, 2018	Aria support

1. Overview

Objectives

The igx-grid should support selection of one or more rows.

The igx-grid should support selection of one or more rows, through a checkbox that is preceding all other columns in the row. Clicking the checkbox will select/deselect the row, and selection will not happen when clicking any other cell in the row. Checkbox column will be fixed, which will leave it visible, even a horizontal scrollbar is presented.

2. User Stories

As an end user, I want to

to select/deselect grid rows, using a checkbox
to select/deselect checkbox, using space key
the checkbox column to be always the first column
the checkbox column to be always visible
to have checkbox in header that will select/deselect all visible rows
the header checkbox to have indeterminate state, which will be visible, when 1 or more, but but not all the rows are selected
preserve selection, even the selected rows are out of visual scope
filter grid data, then use the header checkbox to select all visible rows. When filter is cleared, then only the previously filtered items are selected
if filtering is applied then header checkbox will show state only for the filtered items, and clicking the header checkbox will select all filtered items, and will make the header checkbox selected (not indeterminate state, because it will not be related to all the items)
if paging is enabled in the grid then selecting header checkbox will select all the rows on all the pages

Developer Stories

As a developer, I want to

get/set selected rows collection
get/set selected rows using their identifiers (primaryKey or rowData)
select/deselect all rows
be notified, when selection has changed
select/deselect single rowComponent

3. Functionality

3.1. End User Experience

Users are able to select and deselect row, using a checkbox, that is pinned at the start of the row.

3.2. Developer Experience

Enabling the row selection behavior in the grid is as easy as:

<igx-grid #grid [data]="localData" [rowSelectable]="true"></igx-grid>

Developers are able to programmatically select/deselect rows. The identification of the rows, happen according the the grid primaryKey.

Selection of rows is as easy as:

this.grid.selectRows([rowID1,rowID3,rowID5]);

Developers can also subscribe to an event emitted before the row selection is copmleted:

<igx-grid #grid [data]="localData" [rowSelectable]="true" (onRowSelection)="rowSelection($event)"></igx-grid>

public rowSelection(event) {
    const grid = event.row.grid;
    grid.deselectAllRows();
    grid.selectRows([event.row]);
}

3.3 Other igxGrid features integration

Filtering
Sorting
Paging

Row selection should preserve selection, during data operations, like the one above. When a grid data is filtered and then header checkbox is selected, only the visible items should be added to the selection. The same is not valid for paging - when header checkbox is clicked then all the items on all the pages are selected.

3.4. Keyboard Interaction

As far as the default way to select a row is using, the checkbox, then focusing the checkbox and using the Space, will toggle the selection. Focusing the checkbox will apply focus state to the checkbox, while the container of the checkbox will not get the style of a selected cell.

3.5 API

Properties

IgxGridComponent

Name Description Type

rowSelectable Enable row selection for the grid boolean

Methods

IgxGridComponent

Name	Description	Return type	Parameters
selectedRows	Get current selection state	`Array<any>`- array with selected rows' ID (primaryKey or rowData)
selectedVisibleRows	Get current selection state	`Array<IgxRowComponent>`- array with selected visible rows
selectRows	Select specified rows by ID	`bool`- whether the select was successful or not	`Array<any>`, clearCurrentSelection: `boolean`
selectVisibleRows	Select specified rows	`bool`- whether the select was successful or not	`Array<IgxRowComponent>`, clearCurrentSelection: `boolean`
deselectRows	Deselect specified rows	`bool`- whether the deselect is successful or not	`Array<any>`
deselectVisibleRows	Deselect specified rows	`bool`- whether the deselect is successful or not	`Array<IgxRowComponent>`
selectAllRows	Select all rows	`bool`- whether the select is successful or not
selectAllVisibleRows	Select all rows	`bool`- whether the select is successful or not
deselectAllRows	Select all rows	`bool`- whether the deselect is successful or not
deselectAllVisibleRows	Select all rows	`bool`- whether the deselect is successful or not

IgxGridRowComponent

Name	Description	Return type
isSelected		`bool` - whether the row is selected or not
select	Select this row	`bool` - whether the select is successful or not
deselect	Deselect this row	`bool` - whether the deselect is successful or not

Note: those row methods/options will work only when rowSelectable is true

Events

Name	Description	Cancelable	Parameters
onRowSelection	Emitted when selection is changed, before the selection completes.	true	{ selection: `Array<any>`, row: IgxRowComponent, rowID: any

Note: cell selection will trigger onSelection and not onRowSelection

4. ARIA Support

The following components gets the corresponding aria attributes

row - aria-selected
header checkbox - aria-checked, aria-label="Select all"/"Select all filtered"
row checkbox - aria-checked, aria-label="Select row with key ${primaryKey}"/"Select row"; when primary key is omitted, then it's not possible to describe row as a string

5. Assumptions and Limitations

Following the Material Design Guidelines the following setting where omitted, to allow easy configuration of the feature. All the below can be achieved, using the row selection API.