Y.DataTable.Selection Class
A class extension for DataTable that adds "highlight" and "select" actions via mouse selection. The extension works in either "cell" mode or "row" mode (set via attribute selectionMode).
Highlighting is controlled by the highlightMode attribute (either "cell" or "row"). (Highlighting provides a "mouseover" indication only), and a delegated "mouseover" event is defined in this module.
Selection is provided via "click" listeners, by setting a delegated "click" handler on the TD or TR elements.
This extension includes the ability to select "multiple" items, by setting the selectionMulti attribute (enabled using browser multi-select click modifier, i.e. "Cmd" key on Mac OSX or "Ctrl" key on Windows / Linux).
Additionally, a "range" selection capability is provided by using the browser range selector click key modifier, specifically the Shift key on most systems.
The extension has been written to allow preserving the "selected" rows or cells during "sort" operations. This is accomplished by storing the selected TR's basis record, specifically the "clientId" attribute which remains unique after sorting operations.
Specific attributes are provided that can be read for current selections, including the ATTRS selectedRows, and selectedCells.
Typical usage would be to set the "selectionMode" and "highlightMode" attributes (and selectionMulti if desired) and then to provide a positive control (like a BUTTON or A link) to process the selections. Two events are provided, selection and selected but these fire for every "click" action, which may not be ideal -- especially for multi selections.
Item Index
Methods
- _afterResetDataSelect
- _bindSelector
- _clearAll
- _clearDOMSelection
- _getSelectedCells
- _getSelectedRows
- _highlightChange
- _processNodeAction
- _processRange
- _selectedChange
- _selectTd
- _selectTr
- _setHighlightMode
- _setSelectedCells
- _setSelectedRows
- _setSelectionMode
- _unbindSelector
- clearAll
- clearHighlighted
- clearSelections
- destructor
- disableSelection
- disableSelection
- getColumnByTd
- getColumnNameByTd
- initializer
Properties
- _classHighlight static
- _classSelected static
- _clickModifiers static
- _selections static
- _subscrHighlight static
- _subscrSelect static
- _subscrSelectComp static
Attributes
Methods
_afterResetDataSelect
()
private
Method is fired AFTER a "reset" action takes place on the "data", usually related to a column sort. This function reads the pre-sorted selections that were stored by beforeResetDataSelect temporarily in this.selections.
Depending upon the current "selectionMode", either post-sorted TBODY selections are re-applied, by determining either the TR's (from the Model data) or the TD's (from the Model and Column Index data).
_bindSelector
()
private
Sets listeners and initial class names required for this "datatable-selector" module
Note: Delegated "click" listeners are defined in _setSelectedMode and _setHightlightMode methods
_clearAll
-
type
Method removes the specified type CSS class from all nodes within the TBODY data node.
Parameters:
-
typeStringClass name to remove from all nodes attached to TBODY DATA
_clearDOMSelection
()
private
Helper method to clear DOM "selected" text or ranges
_getSelectedCells
()
Array
private
Getter method that returns an Array of the selected cells in record/column coordinate format. If rows or TR elements were selected, it adds all of the row's child TD's.
Returned cells {Array} of objects in format;
cells.td{Node} TD Node for this cell.cells.record{Model} Record for this cell as a Y.Modelcells.recordIndex{Integer} Record index for this cell in the current "data" setcells.column{Object} Column for this cell defined in original "columns" DataTable attributecells.columnName{String} Column name or key associated with this cellcells.columnIndex{Integer} Column index of the column, within the "columns" data
Returns:
_getSelectedRows
()
Array
private
Returns the current settings of row selections, includes multiple selections. If the
current selectionMode is "cell" mode, this function returns the unique "records" associated with
the selected cells.
Returned rows {Array} of objects in format;
rows.tr{Node} Node instance of the TR that was selectedrows.record{Model} The Model associated with the data record for the selected TRrows.recordIndex{Integer} The record index of the selected TR within the current "data" set- `rows.recordClientId {String} The record clientId attribute setting
Returns:
_highlightChange
-
o
Method that updates the "highlighted" classes for the selection and unhighlights the prevVal
Parameters:
-
oObject
_processNodeAction
-
o -
prefix -
erasePrev
Method used to derive from the clicked selection, either the TR or TD of the selection, and
returns the current selectionMode or highlightMode Node (based on the setting of prefix).
This method adds the required class, and if erasePrev is true, removes the class from the prior setting.
Parameters:
-
oObjectAttribute change event object
-
prefixString -
erasePrevBoolean
Returns:
selectionMode or highlightMode
_processRange
-
o
Called when a "range" selection is detected (i.e. SHIFT key held during click) that selects a range of TD's or TR's (depending on selectionMode setting.
Parameters:
-
oNodeLast clicked TD of range selection
_selectedChange
-
o
Method that updates the "selected" classes for the selection and un-selects the prevVal.
This method works with multiple selections (via ATTR selectionMulti true) by pushing
the current selection to the this._selections property.
Parameters:
-
oObject
_selectTd
-
tar
Method that returns a TD's "selection obj" expected for the _selections buffer
Parameters:
-
tarNodeA Node instance of TD to be prepared for selection
Returns:
_selectTr
-
tar
Method that returns a TR's "selection obj" expected for the _selections buffer
Parameters:
-
tarNodeA Node instance of TR to be prepared for selection
Returns:
_setHighlightMode
-
val
Setter for highlightMode attribute, removes prior event handle (if exists) and defines
a new delegated "mouseover" handler that updates the highlighted attribute.
A change to this setting clears all prior highlighting.
Parameters:
-
valObject
Returns:
_setSelectedCells
-
val
Setter method for attribute selectedCells that takes an array of cells as input and sets them
as the current selected set with appropriate visual class.
Parameters:
-
valArrayThe desired cells to set as selected, in {record:,column:} format
-
recordString | NumberRecord for this cell as either record index or record clientId
-
columnString | NumberColumn for this cell as either the column index or "key" or "name"
-
Returns:
_setSelectedRows
-
val
A setter method for attribute selectedRows that takes as input an array of desired DataTable
record indices to be "selected", clears existing selections and sets the "selected" records and
highlights the TR's
Parameters:
-
valArrayArray of record indices (or record "clientId") desired to be set as selected.
Returns:
_setSelectionMode
-
val
Setter for selectionMode attribute, removes prior event handle (if exists) and defines
a new delegated "click" handler that updates the selected attribute.
A change to this setting clears all prior selections.
Parameters:
-
valObject
Returns:
_unbindSelector
()
private
Cleans up listener event handlers and static properties.
clearAll
()
public
Removes all highlighting and selections on the DataTable.
clearHighlighted
()
public
Removes all "highlight" classes from DataTable and resets highlighted attribute.
clearSelections
()
public
Removes all "selected" classes from DataTable and resets internal selections counters and "selected" attribute.
destructor
()
protected
Destructor to clean up bindings.
disableSelection
()
public
Method to disable the datatable-selection module (cleans up listeners and user interface).
disableSelection
()
public
Method to enable the datatable-selection module
getColumnByTd
-
cell
Returns the Column object (from the original "columns") associated with the input TD Node.
Parameters:
-
cellNodeNode of TD for which column object is desired
Returns:
getColumnNameByTd
-
cell
Returns the column "key" or "name" string for the requested TD Node
Parameters:
-
cellNodeNode of TD for which column name is desired
Returns:
initializer
()
protected
Initializes and sets initial bindings for the datatable-selection module
Properties
_classHighlight
String
protected
static
Holder for the classname for the "highlight" TR or TD
Default: null
_classSelected
String
protected
static
Holder for the classname for the "selected" TR or TD
Default: null
_clickModifiers
Object
protected
static
Holder for the most recent "click" event modifier keys from last click, used for assessing "multi" selections.
Contains properties; altKey, ctrlKey, shiftKey, metaKey, button and which
Filled initially by .initializer and on each Table "click".
Default: null
_selections
Array
protected
static
Default: null
_subscrHighlight
EventHandle
protected
static
Holder for the event subscription handles so that this compoent can be destroyed by removing listeners
Default: null
_subscrSelect
EventHandle
protected
static
Holder for the event subscription handles so that this compoent can be destroyed by removing listeners
Default: null
_subscrSelectComp
Array of EventHandles
protected
static
Holder for the event subscription handles so that this compoent can be destroyed by removing listeners
Default: null
Attributes
highlightMode
String
Set the current mode for highlighting, either for a single TD (as "cell") or for a full TR (as "row") or "none" for no highlighting
Default: 'none'
selectedCells
Array
Attribute that holds the selected TD's associated with the selected "cells", or related to the
selected "rows" if that is the selectionMode.
On input, an Array can be provided to pre-set as "selected" cells, defined as each element being in {record,column} format; where "record" is the record index (or clientId) and "column" is either the column index or the key/name for the column. (Please see method _setSelectedCells for reference).
dt.set('selectedCells',[{record:0,column:'fname'}, {record:187,column:7} ]);
For reading the selected cells (via "get"), an array is returned with contains {Object} elements that describe the row / column combinations of each currently selected cell. (Please see method _getSelectedCells for full information on the returned objects).
Default: []
selectedRows
Array
Attribute that holds the selected TR's associated with either the selected "rows" or the TR's that are related to the selected "cells", duplicates are excluded.
On input, accepts an Array of record indices for rows that should be set as "selected". (Please refer to method _setSelectedRows)
dt.set('selectedRows',[ 1, 5, 9, 11]);
// selects the 2nd, 6th, 10th and 12th records
For reading this setting, it returns an Array of objects containing {tr,record,recordIndex} for each selected "row"; where "tr" is a Y.Node instance and "record" is the Model for the TR and "recordIndex" is the record index within the current dataset. (Please refer to method _getSelectedRows)
Default: []
Events
selected
Event that fires on every "select" action and returns the LAST SELECTED item, either a cell or a row. Please see the event "selection" which provides a cumulative total of all selected items as opposed to just the last item. (Fired from method _selectedChange
Event Payload:
-
objObjectReturn object
-
ochangeObjectChange event object passed from attribute 'selected'
-
recordObjectDataTable record (Y.Model) instance for the selection
-
selection
Event that fires on every DataTable "select" event, returns current selections, either cells or rows depending on the current "selectionMode". (Fired from method _selectedChange
Event Payload:
-
objObjectReturn object
-
selectionModeObjectCurrent setting of attribute selectionMode
-
cellsObjectReturns the current setting of the attribute selectedCells
-
rowsObjectReturns the current setting of the attribute selectedRows
-