add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / grid / plugin / Editing.js

/**\r
 * This class provides an abstract grid editing plugin on selected {@link Ext.grid.column.Column columns}.\r
 * The editable columns are specified by providing an {@link Ext.grid.column.Column#editor editor}\r
 * in the {@link Ext.grid.column.Column column configuration}.\r
 *\r
 * **Note:** This class should not be used directly. See {@link Ext.grid.plugin.CellEditing} and\r
 * {@link Ext.grid.plugin.RowEditing}.\r
 */\r
Ext.define('Ext.grid.plugin.Editing', {\r
    extend: 'Ext.plugin.Abstract',\r
    alias: 'editing.editing',\r
\r
    requires: [\r
        'Ext.grid.column.Column',\r
        'Ext.util.KeyNav',\r
        // Requiring Ext.form.field.Base and Ext.view.Table ensures that grid editor sass\r
        // variables can derive from both form field vars and grid vars in the neutral theme\r
        'Ext.form.field.Base',\r
        'Ext.view.Table'\r
    ],\r
\r
    mixins: [\r
        'Ext.mixin.Observable'\r
    ],\r
\r
    /**\r
     * @cfg {Number} clicksToEdit\r
     * The number of clicks on a grid required to display the editor.\r
     * The only accepted values are **1** and **2**.\r
     */\r
    clicksToEdit: 2,\r
\r
    /**\r
     * @cfg {String} triggerEvent\r
     * The event which triggers editing. Supersedes the {@link #clicksToEdit} configuration. May be one of:\r
     *\r
     *  * cellclick\r
     *  * celldblclick\r
     *  * cellfocus\r
     *  * rowfocus\r
     */\r
    triggerEvent: undefined,\r
\r
    /**\r
     * @property {Boolean} editing\r
     * Set to `true` while the editing plugin is active and an Editor is visible.\r
     */\r
\r
    relayedEvents: [\r
        'beforeedit',\r
        'edit',\r
        'validateedit',\r
        'canceledit'\r
    ],\r
\r
    /**\r
     * @cfg {String} default UI for editor fields\r
     */\r
    defaultFieldUI: 'default',\r
\r
    // @private\r
    defaultFieldXType: 'textfield',\r
\r
    // cell, row, form\r
    editStyle: '',\r
\r
    /**\r
     * @event beforeedit\r
     * Fires before editing is triggered. Return false from event handler to stop the editing.\r
     *\r
     * @param {Ext.grid.plugin.Editing} editor\r
     * @param {Object} context The editing context with the following properties:\r
     *  @param {Ext.grid.Panel}         context.grid The owning grid Panel.\r
     *  @param {Ext.data.Model}         context.record The record being edited.\r
     *  @param {String}                 context.field The name of the field being edited.\r
     *  @param {Mixed}                  context.value The field's current value.\r
     *  @param {HTMLElement}            context.row The grid row element.\r
     *  @param {Ext.grid.column.Column} context.column The Column being edited.\r
     *  @param {Number}                 context.rowIdx The index of the row being edited.\r
     *  @param {Number}                 context.colIdx The index of the column being edited.\r
     *  @param {Boolean}                context.cancel Set this to `true` to cancel the edit or return false from your handler.\r
     *  @param {Mixed}                  context.originalValue Alias for value (only when using {@link Ext.grid.plugin.CellEditing CellEditing}).\r
     */\r
\r
    /**\r
     * @event edit\r
     * Fires after editing. Usage example:\r
     *\r
     *     grid.on('edit', function(editor, e) {\r
     *         // commit the changes right after editing finished\r
     *         e.record.commit();\r
     *     });\r
     *\r
     * @param {Ext.grid.plugin.Editing} editor\r
     * @param {Object} context The editing context with the following properties:\r
     *  @param {Ext.grid.Panel}         context.grid The owning grid Panel.\r
     *  @param {Ext.data.Model}         context.record The record being edited.\r
     *  @param {String}                 context.field The name of the field being edited.\r
     *  @param {Mixed}                  context.value The field's current value.\r
     *  @param {HTMLElement}            context.row The grid row element.\r
     *  @param {Ext.grid.column.Column} context.column The Column being edited.\r
     *  @param {Number}                 context.rowIdx The index of the row being edited.\r
     *  @param {Number}                 context.colIdx The index of the column being edited.\r
     */\r
\r
    /**\r
     * @event validateedit\r
     * Fires after editing, but before the value is set in the record. Return false from event handler to\r
     * cancel the change.\r
     *\r
     * Usage example showing how to remove the red triangle (dirty record indicator) from some records (not all). By\r
     * observing the grid's validateedit event, it can be cancelled if the edit occurs on a targeted row (for example)\r
     * and then setting the field's new value in the Record directly:\r
     *\r
     *     grid.on('validateedit', function (editor, context) {\r
             *         var myTargetRow = 6;\r
             *\r
             *         if (context.rowIdx === myTargetRow) {\r
             *             context.record.data[context.field] = context.value;\r
             *         }\r
             *     });\r
     *\r
     * @param {Ext.grid.plugin.Editing} editor\r
     * @param {Object} context The editing context with the following properties:\r
     *  @param {Ext.grid.Panel}         context.grid The owning grid Panel.\r
     *  @param {Ext.data.Model}         context.record The record being edited.\r
     *  @param {String}                 context.field The name of the field being edited.\r
     *  @param {Mixed}                  context.value The field's current value.\r
     *  @param {HTMLElement}            context.row The grid row element.\r
     *  @param {Ext.grid.column.Column} context.column The Column being edited.\r
     *  @param {Number}                 context.rowIdx The index of the row being edited.\r
     *  @param {Number}                 context.colIdx The index of the column being edited.\r
     */\r
\r
    /**\r
     * @event canceledit\r
     * Fires when the user started editing but then cancelled the edit.\r
     * @param {Ext.grid.plugin.Editing} editor\r
     * @param {Object} context The editing context with the following properties:\r
     *  @param {Ext.grid.Panel}         context.grid The owning grid Panel.\r
     *  @param {Ext.data.Model}         context.record The record being edited.\r
     *  @param {String}                 context.field The name of the field being edited.\r
     *  @param {Mixed}                  context.value The field's current value.\r
     *  @param {HTMLElement}            context.row The grid row element.\r
     *  @param {Ext.grid.column.Column} context.column The Column being edited.\r
     *  @param {Number}                 context.rowIdx The index of the row being edited.\r
     *  @param {Number}                 context.colIdx The index of the column being edited.\r
     */\r
\r
    constructor: function(config) {\r
        var me = this;\r
\r
        me.callParent([config]);\r
        me.mixins.observable.constructor.call(me);\r
        // TODO: Deprecated, remove in 5.0\r
        me.on("edit", function(editor, e) {\r
            me.fireEvent("afteredit", editor, e);\r
        });\r
    },\r
\r
    // @private\r
    init: function(grid) {\r
        var me = this,\r
            ownerLockable = grid.ownerLockable;\r
\r
        me.grid = grid;\r
        me.view = grid.view;\r
        me.initEvents();\r
\r
        // Set up fields at render and reconfigure time\r
        if (grid.rendered) {\r
            me.setup();\r
        } else {\r
            me.mon(grid, {\r
                beforereconfigure: me.onBeforeReconfigure,\r
                reconfigure: me.onReconfigure,\r
                scope: me,\r
                beforerender: {\r
                    fn: me.onBeforeRender,\r
                    single: true,\r
                    scope: me\r
                }\r
            });\r
        }\r
\r
        grid.editorEventRelayers = grid.relayEvents(me, me.relayedEvents);\r
\r
        // If the editable grid is owned by a lockable, relay up another level.\r
        if (ownerLockable) {\r
            ownerLockable.editorEventRelayers = ownerLockable.relayEvents(me, me.relayedEvents);\r
        }\r
        // Marks the grid as editable, so that the SelectionModel\r
        // can make appropriate decisions during navigation\r
        grid.isEditable = true;\r
        grid.editingPlugin = grid.view.editingPlugin = me;\r
    },\r
\r
    onBeforeReconfigure: function() {\r
        this.reconfiguring = true;\r
    },\r
\r
    /**\r
     * Fires after the grid is reconfigured\r
     * @protected\r
     */\r
    onReconfigure: function() {\r
        this.setup();\r
        delete this.reconfiguring;\r
    },\r
\r
    onBeforeRender: function() {\r
        this.setup();\r
    },\r
\r
    setup: function() {\r
        // In a Lockable assembly, the owner's view aggregates all grid columns across both sides.\r
        // We grab all columns here.\r
        this.initFieldAccessors(this.grid.getTopLevelColumnManager().getColumns());\r
    },\r
\r
    destroy: function() {\r
        var me = this,\r
            grid = me.grid;\r
\r
        Ext.destroy(me.keyNav);\r
        \r
        // Clear all listeners from all our events, clear all managed listeners we added to other Observables\r
        me.clearListeners();\r
\r
        if (grid) {\r
            if (grid.ownerLockable) {\r
                Ext.destroy(grid.ownerLockable.editorEventRelayers);\r
                grid.ownerLockable.editorEventRelayers = null;\r
            }\r
            \r
            Ext.destroy(grid.editorEventRelayers);\r
            grid.editorEventRelayers = null;\r
            \r
            grid.editingPlugin = grid.view.editingPlugin = me.grid = me.view = me.editor = me.keyNav = null;\r
        }\r
\r
        me.callParent();\r
    },\r
\r
    // @private\r
    getEditStyle: function() {\r
        return this.editStyle;\r
    },\r
\r
    // @private\r
    initFieldAccessors: function(columns) {\r
        // If we have been passed a group header, process its leaf headers\r
        if (columns.isGroupHeader) {\r
            columns = columns.getGridColumns();\r
        }\r
\r
        // Ensure we are processing an array\r
        else if (!Ext.isArray(columns)) {\r
            columns = [columns];\r
        }\r
\r
        var me = this,\r
            c,\r
            cLen = columns.length,\r
            getEditor = function(record, defaultField) {\r
                return me.getColumnField(this, defaultField);\r
            },\r
            hasEditor = function() {\r
                return me.hasColumnField(this);\r
            },\r
            setEditor = function(field) {\r
                me.setColumnField(this, field);\r
            },\r
            column;\r
\r
        for (c = 0; c < cLen; c++) {\r
            column = columns[c];\r
\r
            if (!column.getEditor) {\r
                column.getEditor = getEditor;\r
            }\r
            if (!column.hasEditor) {\r
                column.hasEditor = hasEditor;\r
            }\r
            if (!column.setEditor) {\r
                column.setEditor = setEditor;\r
            }\r
        }\r
    },\r
\r
    // @private\r
    removeFieldAccessors: function(columns) {\r
        // If we have been passed a group header, process its leaf headers\r
        if (columns.isGroupHeader) {\r
            columns = columns.getGridColumns();\r
        }\r
\r
        // Ensure we are processing an array\r
        else if (!Ext.isArray(columns)) {\r
            columns = [columns];\r
        }\r
\r
        var c,\r
            cLen = columns.length,\r
            column;\r
\r
        for (c = 0; c < cLen; c++) {\r
            column = columns[c];\r
            column.getEditor = column.hasEditor = column.setEditor = column.field = column.editor = null;\r
        }\r
    },\r
\r
    // @private\r
    // remaps to the public API of Ext.grid.column.Column.getEditor\r
    getColumnField: function(columnHeader, defaultField) {\r
        var me = this,\r
            field = columnHeader.field;\r
\r
        if (!(field && field.isFormField)) {\r
            field = columnHeader.field = me.createColumnField(columnHeader, defaultField);\r
        }\r
\r
        if (field && field.ui === 'default' && !field.hasOwnProperty('ui')) {\r
            field.ui = me.defaultFieldUI;\r
        }\r
        return field;\r
    },\r
\r
    // @private\r
    // remaps to the public API of Ext.grid.column.Column.hasEditor\r
    hasColumnField: function(columnHeader) {\r
        return !!(columnHeader.field && columnHeader.field.isComponent);\r
    },\r
\r
    // @private\r
    // remaps to the public API of Ext.grid.column.Column.setEditor\r
    setColumnField: function(columnHeader, field) {\r
        columnHeader.field = field;\r
        columnHeader.field = this.createColumnField(columnHeader);\r
    },\r
\r
    createColumnField: function (column, defaultField) {\r
        var field = column.field,\r
            dataIndex;\r
\r
        if (!field && column.editor) {\r
            field = column.editor;\r
            column.editor = null;\r
        }\r
\r
        if (!field && defaultField) {\r
            field = defaultField;\r
        }\r
\r
        if (field) {\r
            dataIndex = column.dataIndex;\r
\r
            if (field.isComponent) {\r
                field.column = column;\r
            } else {\r
                if (Ext.isString(field)) {\r
                    field = {\r
                        name: dataIndex,\r
                        xtype: field,\r
                        column: column\r
                    };\r
                } else {\r
                    field = Ext.apply({\r
                        name: dataIndex,\r
                        column: column\r
                    }, field);\r
                }\r
                field = Ext.ComponentManager.create(field, this.defaultFieldXType);\r
            }\r
\r
            // Stamp on the dataIndex which will serve as a reliable lookup regardless\r
            // of how the editor was defined (as a config or as an existing component).\r
            // See EXTJSIV-11650.\r
            field.dataIndex = dataIndex;\r
\r
            field.isEditorComponent = true;\r
            column.field = field;\r
        }\r
        return field;\r
    },\r
\r
    // @private\r
    initEvents: function() {\r
        var me = this;\r
        me.initEditTriggers();\r
        me.initCancelTriggers();\r
    },\r
\r
    // @abstract\r
    initCancelTriggers: Ext.emptyFn,\r
\r
    // @private\r
    initEditTriggers: function() {\r
        var me = this,\r
            view = me.view;\r
\r
        // Listen for the edit trigger event.\r
        if (me.triggerEvent === 'cellfocus') {\r
            me.mon(view, 'cellfocus', me.onCellFocus, me);\r
        } else if (me.triggerEvent === 'rowfocus') {\r
            me.mon(view, 'rowfocus', me.onRowFocus, me);\r
        } else {\r
\r
            // Prevent the View from processing when the SelectionModel focuses.\r
            // This is because the SelectionModel processes the mousedown event, and\r
            // focusing causes a scroll which means that the subsequent mouseup might\r
            // take place at a different document XY position, and will therefore\r
            // not trigger a click.\r
            // This Editor must call the View's focusCell method directly when we recieve a request to edit\r
            if (view.getSelectionModel().isCellModel) {\r
                view.onCellFocus = me.beforeViewCellFocus.bind(me);\r
            }\r
\r
            // Listen for whichever click event we are configured to use\r
            me.mon(view, me.triggerEvent || ('cell' + (me.clicksToEdit === 1 ? 'click' : 'dblclick')), me.onCellClick, me);\r
        }\r
\r
        // add/remove header event listeners need to be added immediately because\r
        // columns can be added/removed before render\r
        me.initAddRemoveHeaderEvents();\r
\r
        // Attach new bindings to the View's NavigationModel which processes cellkeydown events.\r
        me.view.getNavigationModel().addKeyBindings({\r
            esc: me.onEscKey,\r
            scope: me\r
        });\r
    },\r
\r
    // Override of View's method so that we can pre-empt the View's processing if the view is being triggered by a mousedown\r
    beforeViewCellFocus: function(position) {\r
        // Pass call on to view if the navigation is from the keyboard, or we are not going to edit this cell.\r
        if (this.view.selModel.keyNavigation || !this.editing || !this.isCellEditable || !this.isCellEditable(position.row, position.columnHeader)) {\r
            this.view.focusCell.apply(this.view, arguments);\r
        }\r
    },\r
\r
    // @private Used if we are triggered by the rowfocus event\r
    onRowFocus: function(record, row, rowIdx) {\r
        this.startEdit(row, 0);\r
    },\r
\r
    // @private Used if we are triggered by the cellfocus event\r
    onCellFocus: function(record, cell, position) {\r
        this.startEdit(position.row, position.column);\r
    },\r
\r
    // @private Used if we are triggered by a cellclick event\r
    // *IMPORTANT* Due to V4.0.0 history, the colIdx here is the index within ALL columns, including hidden.\r
    onCellClick: function(view, cell, colIdx, record, row, rowIdx, e) {\r
        // Make sure that the column has an editor.  In the case of CheckboxModel,\r
        // calling startEdit doesn't make sense when the checkbox is clicked.\r
        // Also, cancel editing if the element that was clicked was a tree expander.\r
        var expanderSelector = view.expanderSelector,\r
        // Use getColumnManager() in this context because colIdx includes hidden columns.\r
            columnHeader = view.ownerCt.getColumnManager().getHeaderAtIndex(colIdx),\r
            editor = columnHeader.getEditor(record);\r
\r
        if (this.shouldStartEdit(editor) && (!expanderSelector || !e.getTarget(expanderSelector))) {\r
            view.ownerGrid.setActionableMode(true, e.position);\r
        }\r
    },\r
\r
    initAddRemoveHeaderEvents: function(){\r
        var me = this,\r
            headerCt = me.grid.headerCt;\r
\r
        me.mon(headerCt, {\r
            scope: me,\r
            add: me.onColumnAdd,\r
            columnmove: me.onColumnMove,\r
            beforedestroy: me.beforeGridHeaderDestroy\r
        });\r
    },\r
\r
    // @private\r
    onColumnAdd: function(ct, column) {\r
        this.initFieldAccessors(column);\r
    },\r
\r
    // Template method which may be implemented in subclasses (RowEditing and CellEditing)\r
    onColumnMove: Ext.emptyFn,\r
\r
    // @private\r
    onEscKey: function(e) {\r
        if (this.editing) {\r
            var targetComponent = Ext.getCmp(e.getTarget().getAttribute('componentId'));\r
\r
            // ESCAPE when a picker is expanded does not cancel the edit\r
            if (!(targetComponent && targetComponent.isPickerField && targetComponent.isExpanded)) {\r
                return this.cancelEdit();\r
            }\r
        }\r
    },\r
\r
    /**\r
     * @method\r
     * @private\r
     * @template\r
     * Template method called before editing begins.\r
     * @param {Object} context The current editing context\r
     * @return {Boolean} Return false to cancel the editing process\r
     */\r
    beforeEdit: Ext.emptyFn,\r
\r
    shouldStartEdit: function(editor) {\r
        return !!editor;\r
    },\r
\r
    /**\r
     * @private\r
     * Collects all information necessary for any subclasses to perform their editing functions.\r
     * @param {Ext.data.Model/Number} record The record or record index to edit.\r
     * @param {Ext.grid.column.Column/Number} columnHeader The column of column index to edit.\r
     * @return {Ext.grid.CellContext/undefined} The editing context based upon the passed record and column\r
     */\r
    getEditingContext: function(record, columnHeader) {\r
        var me = this,\r
            grid = me.grid,\r
            colMgr = grid.visibleColumnManager,\r
            view,\r
            gridRow,\r
            rowIdx, colIdx,\r
            result,\r
            layoutView = me.grid.lockable ? me.grid : me.view;\r
\r
        // The view must have had a layout to show the editor correctly, defer until that time.\r
        // In case a grid's startup code invokes editing immediately.\r
        if (!layoutView.componentLayoutCounter) {\r
            layoutView.on({\r
                boxready: Ext.Function.bind(me.startEdit, me, [record, columnHeader]),\r
                single: true\r
            });\r
            return;\r
        }\r
\r
        // If disabled or grid collapsed, or view not truly visible, don't calculate a context - we cannot edit\r
        if (me.disabled || me.grid.collapsed || !me.grid.view.isVisible(true)) {\r
            return;\r
        }\r
\r
        // They've asked to edit by column number.\r
        // Note that in a locked grid, the columns are enumerated in a unified set for this purpose.\r
        if (Ext.isNumber(columnHeader)) {\r
            columnHeader = colMgr.getHeaderAtIndex(columnHeader);\r
        }\r
\r
        // No corresponding column. Possible if all columns have been moved to the other side of a lockable grid pair\r
        if (!columnHeader) {\r
            return;\r
        }\r
\r
        // Coerce the column to the closest visible column\r
        if (columnHeader.hidden) {\r
            columnHeader = columnHeader.next(':not([hidden])') || columnHeader.prev(':not([hidden])');\r
        }\r
\r
        // Navigate to the view and grid which the column header relates to.\r
        view = columnHeader.getView();\r
        grid = view.ownerCt;\r
\r
        // Ensure the row we want to edit is in the rendered range if the view is buffer rendered\r
        grid.ensureVisible(record, {\r
            column : columnHeader\r
        });\r
        \r
        gridRow = view.getRow(record);\r
\r
        // An intervening listener may have deleted the Record.\r
        if (!gridRow) {\r
            return;\r
        }\r
\r
        // Column index must be relative to the View the Context is using.\r
        // It must be the real owning View, NOT the lockable pseudo view.\r
        colIdx = view.getVisibleColumnManager().indexOf(columnHeader);\r
\r
        if (Ext.isNumber(record)) {\r
            // look up record if numeric row index was passed\r
            rowIdx = record;\r
            record = view.getRecord(gridRow);\r
        } else {\r
            rowIdx = view.indexOf(gridRow);\r
        }\r
\r
        // The record may be removed from the store but the view\r
        // not yet updated, so check it exists\r
        if (!record) {\r
            return;\r
        }\r
\r
        // Create a new CellContext\r
        result = new Ext.grid.CellContext(view).setAll(view, rowIdx, colIdx, record, columnHeader);\r
\r
        // Add extra Editing information\r
        result.grid = grid;\r
        result.store = view.dataSource;\r
        result.field = columnHeader.dataIndex;\r
        result.value = result.originalValue = record.get(columnHeader.dataIndex);\r
        result.row = gridRow;\r
        result.node = view.getNode(record);\r
        result.cell = view.getCellByPosition(result, true);\r
\r
        return result;\r
    },\r
\r
    /**\r
     * Cancels any active edit that is in progress.\r
     */\r
    cancelEdit: function() {\r
        var me = this;\r
\r
        me.editing = false;\r
        me.fireEvent('canceledit', me, me.context);\r
    },\r
\r
    /**\r
     * Completes the edit if there is an active edit in progress.\r
     */\r
    completeEdit: function() {\r
        var me = this;\r
\r
        if (me.editing && me.validateEdit()) {\r
            me.fireEvent('edit', me, me.context);\r
        }\r
\r
        me.context = null;\r
        me.editing = false;\r
    },\r
\r
    // @abstract\r
    validateEdit: function(context) {\r
        var me = this;\r
\r
        return me.fireEvent('validateedit', me, context) !== false && !context.cancel;\r
    }\r
});