Y.DataTable.BaseCellInlineEditor Class
A View class that serves as the BASE View class for a TD Cell "inline" editor, i.e. an editor that is a single INPUT node that completely overlies the TD cell. This editor is intended to replicate the familiar "spreadsheet" type of input.
Editing / Validation
This editor view creates a simple INPUT[type=text] control and repositions and resizes it to match the underlying TD, set with a z-Index to visually appear over the TD cell.
Key listeners are provided to detect changes, prohibit invalid keystrokes (via the keyFiltering setting) and to allow validation upon a "save" entry (keyboard RTN stroke) where a validator can be prescribed to allow/disallow changes based upon the overall "value" of the INPUT control.
Navigation
The editor provides the capability to navigate from TD cell via key listeners on the following key combinations; * CTRL-arrow keys * TAB goes to RIGHT, SHIFT-TAB goes to left * ESC cancels editing * RTN saves cell
Key navigation can be disabled via the inputKeys attribute set to false.
When a "key navigation" request is received it is passed to the keyDir as a change
in [row,col] that implementers can listen to "change" events on, to reposition and open editing on the
new relative cell. (NOTE: This view does not reposition, it simply fires a keyDirChange event.
Events
Several events are fired by this View; which can be listened for and acted upon to achieve differing results. For example, the Y.DataTable.EditorOptions.inlineAC (inline autocompletion editor) listens for the editorCreated event and once received, it configures the autocomplete plugin onto the INPUT node.
Configuration
Ths Y.DataTable.BaseCellInlineEditor editor is intended to be configured by varying the configuration parameters (i.e. attribute and related configuration) to permit a variety of editing features.
Since the View class permits ad-hoc attributes, the implementer can pass many properties in during instantiation that will become available as run-time View attributes.
This Module includes several pre-defined editor configurations which are stored within the Y.DataTable.EditorOptions
namespace (presently there are "inline", "inlineNumber", "inlineDate", "inlineAC"). New inline editors can be
created and added to this namespace at runtime, and by defining the BaseViewClass:Y.DataTable.BaseCellInlineEditor property.
For example, the pre-built configuration object for the inlineDate inline editor
is stored as Y.DataTable.EditorOptions.inlineDate.
To configure an editor on-the-fly (i.e. within a DataTable column definition) just include the configuration object options
within DT's column editorConfig object, which is Y.merge'ed with the pre-built configs;
// define an 'inlineDate' editor with additional configs ...
{ key:'date_of_claim', editor:"inlineDate", editorConfig:{ dateformat:'%Y-%m-%d'} }
This Y.DataTable.BaseCellinlineEditor class is similar to (and compatible with ) the Y.DataTable.BaseCellPopupEditor
in another gallery module. Note that since the "inline" editor uses a simple INPUT[type=text] Node instead of an
Overlay the codeline is quite a bit simpler.
KNOWN ISSUES:
- This View doesn't work well with scrolling DT's, so I've disabled it currently.
- Sometimes after a DT's
editableATTR is toggled true/false a "cannot read 'style'" message occurs and editing failes requiring a page refresh.
Item Index
Methods
Properties
- _classInput static
- _inputNode static
- _subscr static
- events static
- template static
Attributes
Methods
_bindUI
()
private
Adds a listener to this editor instance to reposition based on "xy" attribute changes
_createUI
()
private
Processes the initial container for this View, sets up the HTML content and creates a listener for positioning changes
_defEditorCancelFn
()
private
The defaultFn for the editorCancel event
_defEditorSaveFn
-
e
The defaultFn for the editorSave event
Parameters:
-
eEventFacadeFor editorSave event
_onClick
-
o
Listener to INPUT "click" events that will stop bubbling to the DT TD listener, to prevent closing editing while clicking within an INPUT.
Parameters:
-
oEventFacade
_onMouseLeave
()
private
Listener to mouseleave event that will hide the editor if attribute "hideMouseLeave" is true
_parseStyle
-
el -
v
Helper method that returns the computed CSS style for the reference node as a parsed number
Parameters:
-
elNodeNode instance to check style on
-
vStringStyle name to return
Returns:
_resizeCont
-
cont -
td
Resizes the view "container" to match the dimensions of the TD cell that is being edited.
Parameters:
-
contNodeThe Node instance of the "container" of this view
-
tdNodeThe Node instance for the TD to match dimensions of
_setEditorXY
-
e
This method can be used to quickly reset the current View editor's position, used for scrollable DataTables.
NOTE: Scrollable inline editing is a little "rough" right now
Parameters:
-
eEventFacadeThe xy attribute change event facade
_unbindUI
()
private
Detaches any listener handles created by this view
cancelEditor
()
public
Called when the user has requested to cancel, and abort any changes to the DT cell, usually signified by a keyboard ESC or "Cancel" button, etc..
destructor
()
public
Cleans up the View after it is destroyed
hideEditor
()
public
Hides the current editor View instance. If the optional hideMe param is true this View will
be temporarily "hidden" (used for scrolling DT's when the TD is scrolled off/on to the page)
initializer
()
public
Initialize and create the View contents
Returns:
processKeyDown
-
e
Key listener for the INPUT inline editor, "keydown" is checked for non-printing key strokes, navigation or ESC.
This method is intended to overridden by implementers in order to customize behaviors.
Parameters:
-
eEventFacadeKeydown event facade
processKeyPress
-
e
Provides a method to process keypress entries and validate or prevent invalid inputs. This method is meant to be overrideable by implementers to customize behaviors.
Parameters:
-
eEventFacadeKey press event object
saveEditor
-
val
Saves the View's value setting (usually after keyboard RTN or other means) and fires the
editorSave event so consumers (i.e. DataTable) can make final changes to the
Model or dataset.
Thank you to Satyam for his guidance on configuring the event publishing, defaultFn related to this technique!
Parameters:
-
valString | Number | DateRaw value setting to be saved after editing
showEditor
-
td
Displays the inline cell editor and positions / resizes the INPUT to overlay the edited TD element.
Set the initial value for the INPUT element, after preprocessing (if reqd)
Parameters:
-
tdNodeThe Node instance of the TD to begin editing on
Properties
_classInput
String
protected
static
CSS classname to identify the editor's INPUT Node
Default: 'yui3-datatable-inline-input'
_inputNode
Node
protected
static
Placeholder for the created INPUT Node created within the View container
Default: null
_subscr
Array of EventHandles
protected
static
Array of detach handles to any listeners set on this View class
Default: null
events
Object
static
Defines the View container events and listeners used within this View
Default: See Code
template
String
static
Defines the INPUT HTML content "template" for this editor's View container
Default: '<input type="text" class="{cssInput}" />'
Attributes
cell
Object
A cell reference object populated by the calling DataTable, contains the following key properties: {td,value,recClientId,colKey}
Default: {}
className
String
Prescribes a CSS class name to be added to the editor's INPUT node after creation.
Default: null
hideMouseLeave
Boolean
This flag dictates whether the View container is hidden when the mouse leaves the focus of the inline container. Typically we want this behavior, one example where we don't would be an inline autocomplete editor.
Default: true
inputKeys
Boolean
A flag to indicate if cell-to-cell navigation should be implemented (currently setup for CTRL-arrow key, TAB and Shift-TAB) capability
Default: true
keyDir
Array as row,col from current TD
Tracks navigation changes during keyboard input as relative [row,col] changes from the currently active cell TD.
Default: []
keyFiltering
RegExp | Function
Provides a keystroke filtering capability to restrict input into the editing area checked during the "keypress" event. This attribute is set to either a RegEx or a function that confirms if the keystroke was valid for this editor. (TRUE meaning valid, FALSE meaning invalid)
If a function is provided, the single argument is the keystroke event facade e and if
the keystroke is valid it should return true, otherwise if invalid false;
Default: null
Example:
/\d/ // for numeric digit-only input
/\d|\-|\./ // for floating point numeric input
/\d|\// // for Date field entry in MM/DD/YYYY format
lastValue
String | Number | Date
Value that was contained in the cell when the Editor View was displayed
Default: null
prepFn
Function
Function to execute on the "data" contents just prior to displaying in the Editor's main view (i.e. typically used for pre-formatting Date information from JS to mm/dd/YYYY format)
This function will receive one argument "value" which is the data value from the record, and the function runs in Editor scope.
Default: null
saveFn
Function
Function to execute when Editing is complete, prior to "saving" the data to the Record (Model) This function will receive one argument "value" which is the data value from the INPUT and within the scope of the current View instances.
This method is intended to be used for input validation prior to saving. If the returned value is "undefined" the cancelEditor method is executed.
Default: null
validator
RegExp | Function
Provides the capability to validate the final saved value after editing is finished. This attribute can be set to either a RegEx or a function, that operates on the entire "value" setting of the editor input (whereas keyFiltering performs validation checks on each key input).
If a function is provided, the single argument is the value setting of the editor. the keystroke is valid it should return true, otherwise if invalid false;
Default: null
Example:
/\d/ // for numeric digit-only input
/\d|\-|\.|\+/ // for floating point numeric input
/\d|\// // for Date field entry in MM/DD/YYYY format
Events
editorCancel
Fired when editing is cancelled (without saving) on this cell editor
Event Payload:
-
rtnObjectReturned object
-
tdNodeTD Node for the edited cell
-
cellObjectCurrent cell object
-
oldValueString | Number | DateData value of this cell prior to editing
-
editorCreated
View event fired when the inline editor has been initialized and ready for usage. This event can be listened to in order to add additional content or widgets, etc onto the View's container.
Event Payload:
-
rtnObjectReturned object
-
inputNodeNodeThe created INPUT[text] node
-
containerObjectThe View container
-
editorDestroyed
Event fired when the cell editor View is destroyed.
Implementers can listen for this event to check if any sub-components / widgets, etc.. they had created as part of this View need to be destroyed or listener unbound.
editorHide
Fired when the active cell editor is hidden
editorSave
Event that is fired when the user has finished editing the View's cell contents (signified by either a keyboard RTN entry or "Save" button, etc...).
This event is intended to be the PRIMARY means for implementers to know that the editing has been completed and validated. Consumers (i.e. DataTable) should listen to this event and process it's results to save to the Model and or dataset for the DT.
Event Payload:
-
rtnObjectReturned object
-
tdNodeTD Node for the edited cell
-
cellObjectCurrent cell object
-
oldValueString | Number | DateData value of this cell prior to editing
-
newValueString | Number | DateData value of this cell after editing
-
editorShow
Event fired when the cell editor is displayed and becomes visible.
Implementers may listen for this event if they have configured complex View's, that include other widgets or components, to update their UI upon displaying of the view.
Event Payload:
-
rtnObjectReturned object
-
tdNodeTD Node instance of the calling editor
-
inputNodeNodeThe editor's INPUT / TEXTAREA Node
-
valueString | Number | DateThe current "value" setting
-
cellObjectobject
-