Skip to content

Row Selection (Grid feature)

Nikolay Alipiev edited this page Apr 2, 2018 · 20 revisions

Row Selection Specification

Contents

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

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;

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.

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
  • preserver 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

Developer Stories

As a developer, I want to

  • get/set selected rows collection
  • select/deselect all rows
  • be notified, when selection has changed
  • be able to cancel selection that is in progress

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.

3.5 API

Properties

  1. IgxGridComponent

    Name Description Type
    rowSelectable Enable row selection for the grid boolean

Methods

  1. 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
  2. IgxGridRowComponent

    Name Description Return type Parameters
    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

Events

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

Add aria attribute for the selected row.

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.

  • the only mode of selection will be multiple
  • single selection will be achieved using the onSelection event and its arguments that are holding not only cell, but also row data.
  • the only way to select row, will be through the checkbox.
  • checkbox will be always rendered (along with the header one)

igxGrid Row Selection Issue

Clone this wiki locally