Y.DataTable.Editable Class
A DataTable class extension that configures a DT for "editing", current deployment supports cell editing (and planned near-term support for row editing).
This module is essentially a base wrapper-class to setup DT for editing with the appropriate attributes and listener creation / detachment. The real guts of "datatable-editing" is in the View class definitions, within the gallery-datatable-celleditor-inline and gallery-datatable-celleditor-inline modules (and possibly future editor View class modules).
Functionality
The module is basically intended to keep track of the editing state (via editable attribute) and housekeeping functions with regard to managing editor View instance creation, rendering and destruction.
By design this module attempts to group common editor View instances wherever possible. So for a DT with 14 columns
all set with "inline" View classes only 1 View instance is created.
Likewise if a DT uses 4 different "calendar" editor View types but each one as slightly different "editorConfig",
then this module creates 4 different calendar View instances to handle the different configurations.
Listeners are set for the "cellEditorSave" event and saved to the active "data" setting within this module.
Additional capability is provided for cell editing situations to add CSS classes to TD's which are added to "editable" columns (e.g. cursor) to indicate they are "clickable".
This module works sortable, scrollable (y-scrolling currently) to make changes to the client-side of the DT model (remote updates should be provided via ModelList sync or user-defined listeners.)
Attributes
Presently three attributes are provided; editable, editOpenType and defaultEditor.
The primary ATTR is the editable, which is used to toggle on/off the editing state of the DT instance.
The defaultEditor attribute is used to setup a cell editor View instance to be used on all editable columns that don't already have an editor assigned.
Column Properties
In addition to a few new attributes the module also recognizes some new column properties in order to support cell-editing in particular;
| editable | {Boolean} | Flag to indicate if column is editable (set editable:false to exclude an
individual column) |
|---|---|---|
| editor | {String} | Name of the defined Y.DataTable.EditorOptions View configuration for this column. |
| editorConfig | {Object} | Passed to the View editor class when instantiated, and Y.merge'ed in to become View class attributes. |
When this module is loaded and the "editable:true" attribute is set, it attempts to economize on the "instantiation cost" of creating View instances by identifying only editor Views that are required based upon column definitions and/or the defaultEditor attribute. (e.g. if all columns are "text" editors, only one "text" editor View is instantiated)
... More Info
The module fires the event cellEditorSave, which can be listened for to provide updating of remote data back to a server (assuming a ModelList "sync" layer is NOT used). Haven't provided the equivalent to YUI 2.x's "asyncSubmitter" because I think this event could easily be listened to in order to provide follow-on updating to remote data stores.
A new class Object (Y.DataTable.EditorOptions) is added to the DataTable namespace that serves as the datastore of the editor View configuration properties. Each "key" (object property) within this object is an entrypoint to a specific editor configuration, which are defined in the separate View class extensions (presently gallery-datatable-celleditor-inline and gallery-datatable-celleditor-popup. Please see those for specifics.)
KNOWN ISSUES:
- Works minimally with "y" scrolling, "x" scrolling still needs work.
- Initial editor invocation is limited to "mouse" actions on TD only (although keyboard navigation cell-to-cell is available).
FUTURE:
This module will be amended to add support for "row" editing, if required.
Item Index
Methods
- _afterEditableSort
- _bindCellEditingListeners
- _bindEditable
- _bindEditorScroll
- _buildColumnEditors
- _createCellEditorInstance
- _destroyColumnEditors
- _getAllCellEditors
- _handleCellClick
- _onCellEditorCancel
- _onCellEditorSave
- _onDefaultEditorChange
- _onEditableChange
- _onKeyDirChange
- _onKeyEsc
- _onScrollUpdateCellEditor
- _setEditOpenType
- _unbindCellEditingListeners
- _unbindEditable
- _unsetEditor
- _updateAllEditableColumnsCSS
- _updateEditableColumnCSS
- bindEditorListeners
- destructor
- getCellEditor
- getCellEditors
- getColumnByTd
- getColumnNameByTd
- hideAllCellEditors
- hideCellEditor
- initializer
- openCellEditor
Properties
- _classColEditable static
- _columnEditors static
- _commonEditors static
- _openCell static
- _openColKey static
- _openEditor static
- _openRecord static
- _openTd static
- _subscrCellEditors static
- _subscrCellEditorScrolls static
- _subscrEditable static
- _subscrEditOpen static
Attributes
Events
Methods
_afterEditableSort
()
private
Listener to the "sort" event, so we can hide any open editors and update the editable column CSS after the UI refreshes
_bindCellEditingListeners
()
private
Binds listeners to cell TD "open editing" events (i.e. either click or dblclick) as a result of DataTable setting "editable:true".
Also sets a body listener for ESC key, to close the current open editor.
_bindEditable
()
private
Sets up listeners for the DT editable module,
_bindEditorScroll
()
private
Sets up listeners for DT scrollable "scroll" events
_buildColumnEditors
()
private
Pre-scans the DT columns looking for column named editors and collects unique editors, instantiates them, and adds them to the _columnEditors array. This method only creates View instances that are required, through combination of _commonEditors and _columnEditors properties.
_createCellEditorInstance
-
editorName -
column
This method takes the given editorName (i.e. 'textarea') and if the default editor configuration, adds in any column 'editorConfig' and creates the corresponding cell editor View instance.
Makes shallow copies of editorConfig: { overlayConfig, widgetConfig, templateObject }
Parameters:
-
editorNameStringEditor name
-
columnObjectColumn object
Returns:
_destroyColumnEditors
()
private
Loops through the column editor instances, destroying them and resetting the collection to null object
_getAllCellEditors
()
Array
private
Utility method to combine "common" and "column-specific" cell editor instances and return them
Returns:
_handleCellClick
-
e
Listener to TD "click" events that hides a popup editor is not in the current cell
Parameters:
-
eObject
_onCellEditorCancel
-
o
Listener to the cell editor View's "editorCancel" event. The editorCancel event includes a return object with keys {td,cell,oldValue}
Parameters:
-
oObjectReturned object from cell editor "editorCancel" event
_onCellEditorSave
-
o
Listener to the cell editor View's "editorSave" event, that when fired will update the Model's data value for the approrpriate column.
The editorSave event includes a return object with keys {td,cell,newValue,oldValue}
Note: If a "sync" layer DOES NOT exist (i.e. DataSource), implementers can listen for the "saveCellEditing" event to send changes to a remote data store.
Parameters:
-
oObjectReturned object from cell editor "editorSave" event
_onDefaultEditorChange
-
o
Listener for changes on defaultEditor attribute for this DT. If the default editor is changed to a valid setting, we disable and re-enable editing on the DT to reset the column editors.
Parameters:
-
oEventFacadeChange eventfacade for "defaultEditor" attribute
_onEditableChange
-
o
Listener that toggles the DT editable state, setting/unsetting the listeners associated with cell editing.
Parameters:
-
oEventFacadeChange event facade for "editable" attribute
_onKeyDirChange
-
e
Listens to changes to an Editor's "keyDir" event, which result from the user pressing "ctrl-" arrow key while in an editor to navigate to an cell.
The value of "keyDir" is an Array of two elements, in [row,col] format which indicates the number of rows or columns to be changed to from the current TD location (See the base method .getCell)
Parameters:
-
eEventFacadeThe attribute change event facade for the View's 'keyDir' attribute
_onKeyEsc
-
e
Closes the active cell editor when a document ESC key is detected
Parameters:
-
eEventFacadekey listener event facade
_onScrollUpdateCellEditor
()
private
Listener that fires on a scrollable DT scrollbar "scroll" event, and updates the current XY position of the currently open Editor.
_setEditOpenType
-
v
Setter method for the editOpenType attribute, specifies what TD event to listen to for initiating editing.
Parameters:
-
vString
_unbindCellEditingListeners
()
private
Unbinds the TD click delegated click listeners for initiating editing in TDs
_unbindEditable
()
private
Unbinds ALL of the popup editor listeners and removes column editors. This should only be used when the DT is destroyed
_unsetEditor
()
private
Re-initializes the static props to null
_updateAllEditableColumnsCSS
()
private
Method to update all of the current TD's within the current DT to add/remove the editable CSS
_updateEditableColumnCSS
-
cname -
opt
Method that adds/removes the CSS editable-column class from a DataTable column, based upon the setting of the boolean "opt"
Parameters:
-
cnameStringColumn key or name to alter
-
optBooleanTrue of False to indicate if the CSS class should be added or removed
bindEditorListeners
()
public
Over-rideable method that can be used to do other user bindings ? (like hideEditor on mouseout, etc...)
destructor
()
protected
Cleans up ALL of the DT listeners and the editor View instances and generated private props
getCellEditor
-
col
Utility method to return the cell editor View instance associated with a particular column of the Datatable.
Returns null if the given column is not editable.
Parameters:
-
colObject | String | IntegerColumn identifier, either the Column object, column key or column index
Returns:
getCellEditors
()
Array
Returns all cell editor View instances for the editable columns of the current DT instance
Returns:
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:
hideAllCellEditors
()
private
Utility method that scans through all editor instances and hides them
hideCellEditor
()
public
Cleans up a currently open cell editor View and unbinds any listeners that this DT had set on the View.
initializer
()
protected
Initializer that sets up listeners for "editable" state and sets some CSS names
openCellEditor
-
e
Opens the given TD eventfacade or Node with it's assigned cell editor.
Parameters:
-
eEventFacade | NodePassed in object from an event OR a TD Node istance
Properties
_classColEditable
String
private
static
Shortcut to the CSS class that is added to indicate a column is editable
Default: 'yui3-datatable-col-editable'
_columnEditors
Object
private
static
Placeholder hash that stores cell editors keyed by column key (or column name) where the value for the associated key is either a (a) {String} which references an editor name in the _commonEditors hash or (b) {View} instance for a customized editor View instance (typically one with specified "editorConfig" in the column definition).
The object is populated in method _buildColumnEditors.
Default: null
_commonEditors
Object
private
static
Placeholder hash that stores the "common" editors, i.e. standard editor names that occur within Y.DataTable.EditorOptions and are used in this DT.
This object holds the View instances, keyed by the editor "name" for quick hash reference. The object is populated in method _buildColumnEditors.
Default: null
_openCell
Object
private
static
Holds the cell data for the actively edited TD, a complex object including the following; {td, value, recClientId, colKey}
Default: null
_openColKey
String
private
static
Holds the column key (or name) of the TD cell being edited
Default: null
_openEditor
Y.View
private
static
Holds the View instance of the active cell editor currently displayed
Default: null
_openRecord
Model
private
static
Holds the current record (i.e. a Model class) of the TD being edited (Note: this may not always work, better to use "clientId" of the record, i.e. sorting, etc..)
Default: null
_openTd
Node
private
static
Holds the TD Node currently being edited
Default: null
_subscrCellEditors
Array of EventHandles
private
static
Placeholder Array for TD editor invocation event handles (i.e. click or dblclick) that are set on the TBODY to initiate cellEditing.
Default: null
_subscrCellEditorScrolls
Array of EventHandles
private
static
Placeholder for event handles for scrollable DT that listens to "scroll" events and repositions editor (we need two listeners, one for each of X or Y scroller)
Default: null
_subscrEditable
EventHandle
private
static
Placeholder for the DT level event listener for "editableChange" attribute.
Default: null
_subscrEditOpen
EventHandle
private
static
Placeholder for the DT event listener to begin editing a cell (based on editOpenType ATTR)
Default: null
Attributes
defaultEditor
String | Null
Specifies a default editor name to respond to an editing event defined in _editOpenType attribute. The default editor is used if the DataTable is in editing mode (i.e. "editable:true") and if the column DOES NOT include a property editable:false in its definitions.
Cell editors are typically assigned by setting a column property (i.e. editor:'text' or 'date') on each individual column.
This attribute can be used to set a single editor to work on every column without having to define it on each column.
Default: null
Events
cellEditorCancel
Fired when the open Cell Editor has sent an 'editorCancel' event, typically from a user cancelling editing via ESC key or "Cancel Button"
Event Payload:
-
rtnObjectReturned Object
-
tdNodeThe TD Node that was edited
-
cellObjectThe cell object container for the edited cell
-
recordModelModel instance of the record data for the edited cell
-
colKeyStringColumn key (or name) of the edited cell
-
prevValString | Number | DateThe old (last) value of the underlying data for the cell
-
editorNameStringThe name attribute of the editor that updated this cell
cellEditorSave
Event fired after a Cell Editor has sent the 'editorSave' event closing an editing session. The event signature includes pertinent data on the cell, TD, record and column that was edited along with the prior and new values for the cell.
Event Payload:
-
rtnObjectReturned Object
-
tdNodeThe TD Node that was edited
-
cellObjectThe cell object container for the edited cell
-
recordModelModel instance of the record data for the edited cell
-
colKeyStringColumn key (or name) of the edited cell
-
newValString | Number | DateThe new (updated) value of the underlying data for the cell
-
prevValString | Number | DateThe old (last) value of the underlying data for the cell
-
editorNameStringThe name attribute of the editor that updated this cell