GridSelection
Mixin

A mixin for Grid that handles row and cell selection. See selectionMode for details on how to control what should be selected (rows, cells, columns) and how the selection should work.

const grid = new Grid({ height : 300, appendTo : targetElement, selectionMode : { row : true, checkbox : { region : 'locked' }, showCheckAll : true }, columns : [ { text : 'Id', field : 'id' }, { text : 'First name', field : 'firstName', width : 150 }, { text : 'Surname', field : 'surName', width : 150 } ], data : DataGenerator.generateData(10) }); grid.selectedRecords = [1, 2, 3];

// select a row
grid.selectedRow = 7;

// select a cell
grid.selectedCell = { id: 5, columnId: 'column1' }

// select a record
grid.selectedRecord = grid.store.last;

// select multiple records by ids
grid.selectedRecords = [1, 2, 4, 6]

Configs

Configs are options you supply in a configuration object when creating an instance of this class

selectionMode : GridSelectionMode
Selection configuration settings, change these properties to control how selection works and what can be selected.

When configuring (creating an instance), set this to an object containing only those properties you want to change.
```
new Grid({
    selectionMode : {
       // Enables cell selection
       cell       : true,
       // Enabled cell and record selection by dragging
       dragSelect : true,
       // Enables selection of a column's cells by clicking the column header
       column     : true,
       // Shows a row number column which, when clicked, selected the row/record
       rowNumber  : true
    }
});
```
After the configuring is done, these properties will be monitored for changes, making it possible to alter the selection configuration at any time.
```
// Adds a selection checkbox column and makes that the only way to select
grid.selectionMode.checkboxOnly = true;

// Deactivates the auto selection of rows and cells when keyboard navigating
grid.selectionMode.selectOnKeyboardNavigation = false;
```
Properties
- cell : Booleanfalse
  
  Set to true to enable cell selection. This takes precedence over row selection, but rows can still be selected programmatically or with checkbox or RowNumber selection. Required for column selection
- row : Booleanfalse
  
  Set to true to enable row selection. This takes precedence over row selection. Required for row selection
- multiSelect : Booleantrue
  
  Allow multiple selection with ctrl and [Shift + Click] or with checkbox selection. Required for dragSelect and column selection
- alwaysMultiSelect : Booleantrue
  
  Allow multiple selection by simply clicking a row/checkbox
- checkbox : Boolean/CheckColumnConfigfalse
  
  Set to true to add a checkbox selection column to the grid, or pass a config object for the CheckColumn. Note that the checkbox selection column should not be configured with a field, since it is linked to grid selection and not to record data
- checkboxIndex : Number/String
  
  Positions the checkbox column at the provided index or to the right of a provided column id. Defaults to 0 or to the right of an included RowNumberColumn
- checkboxOnly : Booleanfalse
  
  Select rows only when clicking in the checkbox column. Requires cell selection config to be false and checkbox to be set to true. This setting was previously named rowCheckboxSelection
- showCheckAll : Booleanfalse
  
  Set to true to add a checkbox to the selection column header to select/deselect all rows. Requires checkbox to also be set to true. Not supported when Store is configured with lazyLoad
- showCheckAllInGroupRows : Booleanfalse
  
  Set to true to add a checkbox to group rows to be able to check/uncheck all group members
- deselectFilteredOutRecords : Booleanfalse
  
  Set to true to deselect records when they are filtered out
- includeChildren : Boolean/Stringfalse
  
  Set to true to also select/deselect child nodes when a parent node is selected by toggling the checkbox. Set to 'always' to always select/deselect child nodes.
- includeParents : Boolean/'all'/'some'false
  
  Set to all or true to auto select parent if all its children gets selected. If one gets deselected, the parent will also be deselected. Set to 'some' to select parent if one of its children gets selected. The parent will be deselected if all children gets deselected.
- preserveSelectionOnPageChange : Booleanfalse
  
  In row selection mode, this flag controls whether the Grid should preserve its selection when loading a new page of a paged data store. Defaults to false.
- preserveSelectionOnDatasetChange : Booleantrue
  
  In row selection mode, this flag controls whether the Grid should preserve its selection of cells / rows when loading a new dataset (assuming the selected records are included in the newly loaded dataset)
- deselectOnClick : Booleanfalse
  
  Toggles whether the Grid should deselect a selected row or cell when clicking it
- dragSelect : Booleanfalse
  
  Set to true to enable multiple selection by dragging. Requires to also be set to true. Also requires the RowReorder feature to be set to gripOnly
- selectOnKeyboardNavigation : Booleantrue
  
  Set to false to disable auto-selection by keyboard navigation. This will activate the select keyboard shortcut
- column : Booleanfalse
  
  Set to true to be able to select whole columns of cells by clicking the header. Requires cell to be set to true. Not supported when Store is configured with lazyLoad
- rowNumber : Boolean/RowNumberColumnConfigfalse
  
  Set to true, or a config object to add a RowNumberColumn which, when clicked, selects the row
- selectRecordOnCell : Booleantrue
  
  Set to false not to include the record in the selectedRecords array when one of the record row's cells is selected
Has a corresponding runtime selectionMode property.

Properties

Properties are getters/setters or publicly accessible variables on this class

isGridSelection : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of GridSelection class, or subclass thereof.

isGridSelection : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of GridSelection class, or subclass thereof.
selectedCell : GridLocation/GridLocationConfig

In cell selection mode, this will get the cell selector for the (last) selected cell. Set to an available cell selector to select only that cell. Or use selectCell() instead.
selectedCellCSSSelector : String

READONLY

CSS selector for the currently selected cell. Format is "[data-index=index] [data-column-id=column]".
selectedCells : GridLocation[]/GridLocationConfig[]

In cell selection mode, this will get the cell selectors for all selected cells. Set to an array of available cell selectors. Or use selectCells() instead.
selectedRecord : Model

The last selected record. Set to select a row or use Grid#selectRow. Set to null to deselect all
selectedRecords : Model[]/Number[]
Selected records.

If deselectFilteredOutRecords is false (default) this will include selected records which has been filtered out.

If preserveSelectionOnPageChange is true (defaults to false) this will include selected records on all pages.

If selectRecordOnCell is true (default) this will include any record which has at least one cell selected.

Can be set as array of ids:
```
grid.selectedRecords = [1, 2, 4, 6]
```
selectedRows : Model[]/Number[]
Selected records. Records selected via cell selection is excluded.

If deselectFilteredOutRecords is false (default) this will include selected records which has been filtered out.

If preserveSelectionOnPageChange is true (defaults to false) this will include selected records on all pages.

if selectRecordOnCell is false this will return same records as selectedRecords.

Can be set as array of ids:
```
grid.selectedRecords = [1, 2, 4, 6]
```
selectionMode : GridSelectionMode
Selection configuration settings, change these properties to control how selection works and what can be selected.

When configuring (creating an instance), set this to an object containing only those properties you want to change.
```
new Grid({
    selectionMode : {
       // Enables cell selection
       cell       : true,
       // Enabled cell and record selection by dragging
       dragSelect : true,
       // Enables selection of a column's cells by clicking the column header
       column     : true,
       // Shows a row number column which, when clicked, selected the row/record
       rowNumber  : true
    }
});
```
After the configuring is done, these properties will be monitored for changes, making it possible to alter the selection configuration at any time.
```
// Adds a selection checkbox column and makes that the only way to select
grid.selectionMode.checkboxOnly = true;

// Deactivates the auto selection of rows and cells when keyboard navigating
grid.selectionMode.selectOnKeyboardNavigation = false;
```
Properties
- cell : Booleanfalse
  
  Set to true to enable cell selection. This takes precedence over row selection, but rows can still be selected programmatically or with checkbox or RowNumber selection. Required for column selection
- row : Booleanfalse
  
  Set to true to enable row selection. This takes precedence over row selection. Required for row selection
- multiSelect : Booleantrue
  
  Allow multiple selection with ctrl and [Shift + Click] or with checkbox selection. Required for dragSelect and column selection
- alwaysMultiSelect : Booleantrue
  
  Allow multiple selection by simply clicking a row/checkbox
- checkbox : Boolean/CheckColumnConfigfalse
  
  Set to true to add a checkbox selection column to the grid, or pass a config object for the CheckColumn. Note that the checkbox selection column should not be configured with a field, since it is linked to grid selection and not to record data
- checkboxIndex : Number/String
  
  Positions the checkbox column at the provided index or to the right of a provided column id. Defaults to 0 or to the right of an included RowNumberColumn
- checkboxOnly : Booleanfalse
  
  Select rows only when clicking in the checkbox column. Requires cell selection config to be false and checkbox to be set to true. This setting was previously named rowCheckboxSelection
- showCheckAll : Booleanfalse
  
  Set to true to add a checkbox to the selection column header to select/deselect all rows. Requires checkbox to also be set to true. Not supported when Store is configured with lazyLoad
- showCheckAllInGroupRows : Booleanfalse
  
  Set to true to add a checkbox to group rows to be able to check/uncheck all group members
- deselectFilteredOutRecords : Booleanfalse
  
  Set to true to deselect records when they are filtered out
- includeChildren : Boolean/Stringfalse
  
  Set to true to also select/deselect child nodes when a parent node is selected by toggling the checkbox. Set to 'always' to always select/deselect child nodes.
- includeParents : Boolean/'all'/'some'false
  
  Set to all or true to auto select parent if all its children gets selected. If one gets deselected, the parent will also be deselected. Set to 'some' to select parent if one of its children gets selected. The parent will be deselected if all children gets deselected.
- preserveSelectionOnPageChange : Booleanfalse
  
  In row selection mode, this flag controls whether the Grid should preserve its selection when loading a new page of a paged data store. Defaults to false.
- preserveSelectionOnDatasetChange : Booleantrue
  
  In row selection mode, this flag controls whether the Grid should preserve its selection of cells / rows when loading a new dataset (assuming the selected records are included in the newly loaded dataset)
- deselectOnClick : Booleanfalse
  
  Toggles whether the Grid should deselect a selected row or cell when clicking it
- dragSelect : Booleanfalse
  
  Set to true to enable multiple selection by dragging. Requires to also be set to true. Also requires the RowReorder feature to be set to gripOnly
- selectOnKeyboardNavigation : Booleantrue
  
  Set to false to disable auto-selection by keyboard navigation. This will activate the select keyboard shortcut
- column : Booleanfalse
  
  Set to true to be able to select whole columns of cells by clicking the header. Requires cell to be set to true. Not supported when Store is configured with lazyLoad
- rowNumber : Boolean/RowNumberColumnConfigfalse
  
  Set to true, or a config object to add a RowNumberColumn which, when clicked, selects the row
- selectRecordOnCell : Booleantrue
  
  Set to false not to include the record in the selectedRecords array when one of the record row's cells is selected
Has a corresponding selectionMode config.

Functions

Functions are methods available for calling on the class

getRange( )

private

Used internally to get a range of cell selectors from a start selector to an end selector.
deselectAll( removeCurrentRecordsOnlyfalse, silentfalse )

Deselects all selected rows and cells. If store is filtered, this will unselect all visible rows only. Any selections made prior to filtering remains.
deselectCell( cellSelector )
: GridLocation

If in cell selection mode, this deselects one cell. If not, this deselects the cell's record.
deselectCells( cellSelectors )
: GridLocation[]

If in cell selection mode, this deselects a number of cells. If not, this deselects corresponding records.
deselectRow( recordOrId )

Deselect one row
deselectRows( recordOrIds )

Deselect one or more rows
internalSelectRange( fromSelector, toSelector )
: Object

private

Used internally to select a range of cells or records depending on selectionMode. Used in both shift-selection and for drag selection. Will remember current selection range and replace it with new one when it changes. But a range which is completed (drag select mouse up or a new shift range starting point has been set) will remain. This function will not update UI (that's done in refreshGridSelectionUI).
isCellSelected( cellSelector, includeRow )
: Boolean

Checks whether a cell is selected.
isSelectable( recordCellOrId )
: Boolean

Checks whether a cell or row can be selected.
isSelected( cellSelectorOrId )
: Boolean

Checks whether a row is selected. Will not check if any of a row's cells are selected.
onStoreDataChange( )

private

Triggered from Grid view when the store changes. This might happen if store events are batched and then resumed. Deselects all records which have been removed.
onStoreRecordIdChange( )

private

Triggered from Grid view when the id of a record has changed. Update the collection indices.
onStoreRemove( )

private

Triggered from Grid view when records get removed from the store. Deselects all records which have been removed.
onStoreRemoveAll( )

private

Triggered from Grid view when all records get removed from the store. Deselects all records.
prepareSelection( cellSelectorsToDeselect, cellSelectorsToSelect, deselectAllfalse, forceRecordSelectionfalse )
: Object

private

Used internally to prepare a number of cells or records for selection/deselection depending on if cell selectionMode is activated. This function will not select/deselect anything by itself (that's done in performSelection).
selectAll( )

NON-LAZY-LOAD

This selects all rows. If store is filtered, this will merge the selection of all visible rows with any selection made prior to filtering.
selectCell( options )
: GridLocation

If in cell selection mode, this selects one cell. If not, this selects the cell's record.

Triggers: selectionChange
selectCellRange( from, to )

Selects a range of cells, from a cell selector (GridLocation) to another
selectCells( options )
: GridLocation[]

If in cell selection mode, this selects a number of cells. If not, this selects corresponding records.

Triggers: selectionChange
selectRange( fromId, toId )

Selects rows corresponding to a range of records (from fromId to toId)
selectRow( options )

Select one row

Triggers: selectionChange
selectRows( options )

Select one or more rows
spliceSelectedRecords( index, toRemove, toAdd )

Removes and adds records to/from the selection at the same time. Analogous to the Arraysplice method.

Note that if records that are specified for removal are also in the toAdd array, then those records are not removed and then appended. They remain in the same position relative to all remaining records.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

beforeSelectionChange

PREVENTABLE

Fires before the selection changes. Returning false from a listener prevents the change
dragSelecting

Fires while drag selecting. UI will update with current range, but the cells will not be selected until mouse up. This event can be listened for to perform actions while drag selecting.
selectionChange

The selection has been changed.
selectionModeChange

The selectionMode configuration has been changed.

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onBeforeSelectionChange

PREVENTABLE

Called before the selection changes. Returning false from a listener prevents the change
onDragSelecting

Called while drag selecting. UI will update with current range, but the cells will not be selected until mouse up. This event can be listened for to perform actions while drag selecting.
onSelectionChange

The selection has been changed.
onSelectionModeChange

The selectionMode configuration has been changed.

Type definitions

GridSelectionMode
Properties
- cell : Booleanfalse
  
  Set to true to enable cell selection. This takes precedence over row selection, but rows can still be selected programmatically or with checkbox or RowNumber selection. Required for column selection
- row : Booleanfalse
  
  Set to true to enable row selection. This takes precedence over row selection. Required for row selection
- multiSelect : Booleantrue
  
  Allow multiple selection with ctrl and [Shift + Click] or with checkbox selection. Required for dragSelect and column selection
- alwaysMultiSelect : Booleantrue
  
  Allow multiple selection by simply clicking a row/checkbox
- checkbox : Boolean/CheckColumnConfigfalse
  
  Set to true to add a checkbox selection column to the grid, or pass a config object for the CheckColumn. Note that the checkbox selection column should not be configured with a field, since it is linked to grid selection and not to record data
- checkboxIndex : Number/String
  
  Positions the checkbox column at the provided index or to the right of a provided column id. Defaults to 0 or to the right of an included RowNumberColumn
- checkboxOnly : Booleanfalse
  
  Select rows only when clicking in the checkbox column. Requires cell selection config to be false and checkbox to be set to true. This setting was previously named rowCheckboxSelection
- showCheckAll : Booleanfalse
  
  Set to true to add a checkbox to the selection column header to select/deselect all rows. Requires checkbox to also be set to true. Not supported when Store is configured with lazyLoad
- showCheckAllInGroupRows : Booleanfalse
  
  Set to true to add a checkbox to group rows to be able to check/uncheck all group members
- deselectFilteredOutRecords : Booleanfalse
  
  Set to true to deselect records when they are filtered out
- includeChildren : Boolean/Stringfalse
  
  Set to true to also select/deselect child nodes when a parent node is selected by toggling the checkbox. Set to 'always' to always select/deselect child nodes.
- includeParents : Boolean/'all'/'some'false
  
  Set to all or true to auto select parent if all its children gets selected. If one gets deselected, the parent will also be deselected. Set to 'some' to select parent if one of its children gets selected. The parent will be deselected if all children gets deselected.
- preserveSelectionOnPageChange : Booleanfalse
  
  In row selection mode, this flag controls whether the Grid should preserve its selection when loading a new page of a paged data store. Defaults to false.
- preserveSelectionOnDatasetChange : Booleantrue
  
  In row selection mode, this flag controls whether the Grid should preserve its selection of cells / rows when loading a new dataset (assuming the selected records are included in the newly loaded dataset)
- deselectOnClick : Booleanfalse
  
  Toggles whether the Grid should deselect a selected row or cell when clicking it
- dragSelect : Booleanfalse
  
  Set to true to enable multiple selection by dragging. Requires to also be set to true. Also requires the RowReorder feature to be set to gripOnly
- selectOnKeyboardNavigation : Booleantrue
  
  Set to false to disable auto-selection by keyboard navigation. This will activate the select keyboard shortcut
- column : Booleanfalse
  
  Set to true to be able to select whole columns of cells by clicking the header. Requires cell to be set to true. Not supported when Store is configured with lazyLoad
- rowNumber : Boolean/RowNumberColumnConfigfalse
  
  Set to true, or a config object to add a RowNumberColumn which, when clicked, selects the row
- selectRecordOnCell : Booleantrue
  
  Set to false not to include the record in the selectedRecords array when one of the record row's cells is selected

Source path

Grid/view/mixin/GridSelection.js

Demo

examples/selection

Inheritance tree1

GridSelection

GridSelection
Mixin

See also

Configs

Properties

Properties

Properties

Functions

Events

Event handlers

Type definitions

Properties

Source path

Demo

Inheritance tree1

Contents

GridSelection Mixin

See also

Configs

Properties

Properties

Properties

Functions

Events

Event handlers

Type definitions

Properties

Source path

Demo

Inheritance tree1

Contents

GridSelection
Mixin