src/grid/plugin/RowEditing.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.grid.plugin.RowEditing
  17  * @extends Ext.grid.plugin.Editing
  18  *
  19  * The Ext.grid.plugin.RowEditing plugin injects editing at a row level for a Grid. When editing begins,
  20  * a small floating dialog will be shown for the appropriate row. Each editable column will show a field
  21  * for editing. There is a button to save or cancel all changes for the edit.
  22  *
  23  * The field that will be used for the editor is defined at the
  24  * {@link Ext.grid.column.Column#field field}. The editor can be a field instance or a field configuration.
  25  * If an editor is not specified for a particular column then that column won't be editable and the value of
  26  * the column will be displayed.
  27  *
  28  * The editor may be shared for each column in the grid, or a different one may be specified for each column.
  29  * An appropriate field type should be chosen to match the data structure that it will be editing. For example,
  30  * to edit a date, it would be useful to specify {@link Ext.form.field.Date} as the editor.
  31  *
  32  * {@img Ext.grid.plugin.RowEditing/Ext.grid.plugin.RowEditing.png Ext.grid.plugin.RowEditing plugin}
  33  *
  34  * ## Example Usage
  35  *
  36  *     Ext.create('Ext.data.Store', {
  37  *         storeId:'simpsonsStore',
  38  *         fields:['name', 'email', 'phone'],
  39  *         data:{'items':[
  40  *             {"name":"Lisa", "email":"lisa@simpsons.com", "phone":"555-111-1224"},
  41  *             {"name":"Bart", "email":"bart@simpsons.com", "phone":"555--222-1234"},
  42  *             {"name":"Homer", "email":"home@simpsons.com", "phone":"555-222-1244"},
  43  *             {"name":"Marge", "email":"marge@simpsons.com", "phone":"555-222-1254"}
  44  *         ]},
  45  *         proxy: {
  46  *             type: 'memory',
  47  *             reader: {
  48  *                 type: 'json',
  49  *                 root: 'items'
  50  *             }
  51  *         }
  52  *     });
  53  *
  54  *     Ext.create('Ext.grid.Panel', {
  55  *         title: 'Simpsons',
  56  *         store: Ext.data.StoreManager.lookup('simpsonsStore'),
  57  *         columns: [
  58  *             {header: 'Name',  dataIndex: 'name', field: 'textfield'},
  59  *             {header: 'Email', dataIndex: 'email', flex:1,
  60  *                 editor: {
  61  *                     xtype:'textfield',
  62  *                     allowBlank:false
  63  *                 }
  64  *             },
  65  *             {header: 'Phone', dataIndex: 'phone'}
  66  *         ],
  67  *         selType: 'rowmodel',
  68  *         plugins: [
  69  *             Ext.create('Ext.grid.plugin.RowEditing', {
  70  *                 clicksToEdit: 1
  71  *             })
  72  *         ],
  73  *         height: 200,
  74  *         width: 400,
  75  *         renderTo: Ext.getBody()
  76  *     });
  77  */
  78 Ext.define('Ext.grid.plugin.RowEditing', {
  79     extend: 'Ext.grid.plugin.Editing',
  80     alias: 'plugin.rowediting',
  81
  82     requires: [
  83         'Ext.grid.RowEditor'
  84     ],
  85
  86     editStyle: 'row',
  87
  88     /**
  89      * @cfg {Boolean} autoCancel
  90      * `true` to automatically cancel any pending changes when the row editor begins editing a new row.
  91      * `false` to force the user to explicitly cancel the pending changes. Defaults to `true`.
  92      * @markdown
  93      */
  94     autoCancel: true,
  95
  96     /**
  97      * @cfg {Number} clicksToMoveEditor
  98      * The number of clicks to move the row editor to a new row while it is visible and actively editing another row.
  99      * This will default to the same value as {@link Ext.grid.plugin.Editing#clicksToEdit clicksToEdit}.
 100      * @markdown
 101      */
 102
 103     /**
 104      * @cfg {Boolean} errorSummary
 105      * `true` to show a {@link Ext.tip.ToolTip tooltip} that summarizes all validation errors present
 106      * in the row editor. Set to `false` to prevent the tooltip from showing. Defaults to `true`.
 107      * @markdown
 108      */
 109     errorSummary: true,
 110
 111     /**
 112      * @event beforeedit
 113      * Fires before row editing is triggered. The edit event object has the following properties <br />
 114      * <ul style="padding:5px;padding-left:16px;">
 115      * <li>grid - The grid this editor is on</li>
 116      * <li>view - The grid view</li>
 117      * <li>store - The grid store</li>
 118      * <li>record - The record being edited</li>
 119      * <li>row - The grid table row</li>
 120      * <li>column - The grid {@link Ext.grid.column.Column Column} defining the column that initiated the edit</li>
 121      * <li>rowIdx - The row index that is being edited</li>
 122      * <li>colIdx - The column index that initiated the edit</li>
 123      * <li>cancel - Set this to true to cancel the edit or return false from your handler.</li>
 124      * </ul>
 125      * @param {Ext.grid.plugin.Editing} editor
 126      * @param {Object} e An edit event (see above for description)
 127      */
 128     /**
 129      * @event edit
 130      * Fires after a row is edited. The edit event object has the following properties <br />
 131      * <ul style="padding:5px;padding-left:16px;">
 132      * <li>grid - The grid this editor is on</li>
 133      * <li>view - The grid view</li>
 134      * <li>store - The grid store</li>
 135      * <li>record - The record being edited</li>
 136      * <li>row - The grid table row</li>
 137      * <li>column - The grid {@link Ext.grid.column.Column Column} defining the column that initiated the edit</li>
 138      * <li>rowIdx - The row index that is being edited</li>
 139      * <li>colIdx - The column index that initiated the edit</li>
 140      * </ul>
 141      *
 142      * <pre><code>
 143 grid.on('edit', onEdit, this);
 144
 145 function onEdit(e) {
 146     // execute an XHR to send/commit data to the server, in callback do (if successful):
 147     e.record.commit();
 148 };
 149      * </code></pre>
 150      * @param {Ext.grid.plugin.Editing} editor
 151      * @param {Object} e An edit event (see above for description)
 152      */
 153     /**
 154      * @event validateedit
 155      * Fires after a cell is edited, but before the value is set in the record. Return false
 156      * to cancel the change. The edit event object has the following properties <br />
 157      * <ul style="padding:5px;padding-left:16px;">
 158      * <li>grid - The grid this editor is on</li>
 159      * <li>view - The grid view</li>
 160      * <li>store - The grid store</li>
 161      * <li>record - The record being edited</li>
 162      * <li>row - The grid table row</li>
 163      * <li>column - The grid {@link Ext.grid.column.Column Column} defining the column that initiated the edit</li>
 164      * <li>rowIdx - The row index that is being edited</li>
 165      * <li>colIdx - The column index that initiated the edit</li>
 166      * <li>cancel - Set this to true to cancel the edit or return false from your handler.</li>
 167      * </ul>
 168      * Usage example showing how to remove the red triangle (dirty record indicator) from some
 169      * records (not all).  By observing the grid's validateedit event, it can be cancelled if
 170      * the edit occurs on a targeted row (for example) and then setting the field's new value
 171      * in the Record directly:
 172      * <pre><code>
 173 grid.on('validateedit', function(e) {
 174   var myTargetRow = 6;
 175
 176   if (e.rowIdx == myTargetRow) {
 177     e.cancel = true;
 178     e.record.data[e.field] = e.value;
 179   }
 180 });
 181      * </code></pre>
 182      * @param {Ext.grid.plugin.Editing} editor
 183      * @param {Object} e An edit event (see above for description)
 184      */
 185
 186     constructor: function() {
 187         var me = this;
 188         me.callParent(arguments);
 189
 190         if (!me.clicksToMoveEditor) {
 191             me.clicksToMoveEditor = me.clicksToEdit;
 192         }
 193
 194         me.autoCancel = !!me.autoCancel;
 195     },
 196
 197     /**
 198      * @private
 199      * AbstractComponent calls destroy on all its plugins at destroy time.
 200      */
 201     destroy: function() {
 202         var me = this;
 203         Ext.destroy(me.editor);
 204         me.callParent(arguments);
 205     },
 206
 207     /**
 208      * Start editing the specified record, using the specified Column definition to define which field is being edited.
 209      * @param {Model} record The Store data record which backs the row to be edited.
 210      * @param {Model} columnHeader The Column object defining the column to be edited.
 211      * @override
 212      */
 213     startEdit: function(record, columnHeader) {
 214         var me = this,
 215             editor = me.getEditor();
 216
 217         if (me.callParent(arguments) === false) {
 218             return false;
 219         }
 220
 221         // Fire off our editor
 222         if (editor.beforeEdit() !== false) {
 223             editor.startEdit(me.context.record, me.context.column);
 224         }
 225     },
 226
 227     // private
 228     cancelEdit: function() {
 229         var me = this;
 230
 231         if (me.editing) {
 232             me.getEditor().cancelEdit();
 233             me.callParent(arguments);
 234         }
 235     },
 236
 237     // private
 238     completeEdit: function() {
 239         var me = this;
 240
 241         if (me.editing && me.validateEdit()) {
 242             me.editing = false;
 243             me.fireEvent('edit', me.context);
 244         }
 245     },
 246
 247     // private
 248     validateEdit: function() {
 249         var me = this;
 250         return me.callParent(arguments) && me.getEditor().completeEdit();
 251     },
 252
 253     // private
 254     getEditor: function() {
 255         var me = this;
 256
 257         if (!me.editor) {
 258             me.editor = me.initEditor();
 259         }
 260         return me.editor;
 261     },
 262
 263     // private
 264     initEditor: function() {
 265         var me = this,
 266             grid = me.grid,
 267             view = me.view,
 268             headerCt = grid.headerCt;
 269
 270         return Ext.create('Ext.grid.RowEditor', {
 271             autoCancel: me.autoCancel,
 272             errorSummary: me.errorSummary,
 273             fields: headerCt.getGridColumns(),
 274             hidden: true,
 275
 276             // keep a reference..
 277             editingPlugin: me,
 278             renderTo: view.el
 279         });
 280     },
 281
 282     // private
 283     initEditTriggers: function() {
 284         var me = this,
 285             grid = me.grid,
 286             view = me.view,
 287             headerCt = grid.headerCt,
 288             moveEditorEvent = me.clicksToMoveEditor === 1 ? 'click' : 'dblclick';
 289
 290         me.callParent(arguments);
 291
 292         if (me.clicksToMoveEditor !== me.clicksToEdit) {
 293             me.mon(view, 'cell' + moveEditorEvent, me.moveEditorByClick, me);
 294         }
 295
 296         view.on('render', function() {
 297             // Column events
 298             me.mon(headerCt, {
 299                 add: me.onColumnAdd,
 300                 remove: me.onColumnRemove,
 301                 columnresize: me.onColumnResize,
 302                 columnhide: me.onColumnHide,
 303                 columnshow: me.onColumnShow,
 304                 columnmove: me.onColumnMove,
 305                 scope: me
 306             });
 307         }, me, { single: true });
 308     },
 309
 310     startEditByClick: function() {
 311         var me = this;
 312         if (!me.editing || me.clicksToMoveEditor === me.clicksToEdit) {
 313             me.callParent(arguments);
 314         }
 315     },
 316
 317     moveEditorByClick: function() {
 318         var me = this;
 319         if (me.editing) {
 320             me.superclass.startEditByClick.apply(me, arguments);
 321         }
 322     },
 323
 324     // private
 325     onColumnAdd: function(ct, column) {
 326         if (column.isHeader) {
 327             var me = this,
 328                 editor;
 329
 330             me.initFieldAccessors(column);
 331             editor = me.getEditor();
 332
 333             if (editor && editor.onColumnAdd) {
 334                 editor.onColumnAdd(column);
 335             }
 336         }
 337     },
 338
 339     // private
 340     onColumnRemove: function(ct, column) {
 341         if (column.isHeader) {
 342             var me = this,
 343                 editor = me.getEditor();
 344
 345             if (editor && editor.onColumnRemove) {
 346                 editor.onColumnRemove(column);
 347             }
 348             me.removeFieldAccessors(column);
 349         }
 350     },
 351
 352     // private
 353     onColumnResize: function(ct, column, width) {
 354         if (column.isHeader) {
 355             var me = this,
 356                 editor = me.getEditor();
 357
 358             if (editor && editor.onColumnResize) {
 359                 editor.onColumnResize(column, width);
 360             }
 361         }
 362     },
 363
 364     // private
 365     onColumnHide: function(ct, column) {
 366         // no isHeader check here since its already a columnhide event.
 367         var me = this,
 368             editor = me.getEditor();
 369
 370         if (editor && editor.onColumnHide) {
 371             editor.onColumnHide(column);
 372         }
 373     },
 374
 375     // private
 376     onColumnShow: function(ct, column) {
 377         // no isHeader check here since its already a columnshow event.
 378         var me = this,
 379             editor = me.getEditor();
 380
 381         if (editor && editor.onColumnShow) {
 382             editor.onColumnShow(column);
 383         }
 384     },
 385
 386     // private
 387     onColumnMove: function(ct, column, fromIdx, toIdx) {
 388         // no isHeader check here since its already a columnmove event.
 389         var me = this,
 390             editor = me.getEditor();
 391
 392         if (editor && editor.onColumnMove) {
 393             editor.onColumnMove(column, fromIdx, toIdx);
 394         }
 395     },
 396
 397     // private
 398     setColumnField: function(column, field) {
 399         var me = this;
 400         me.callParent(arguments);
 401         me.getEditor().setField(column.field, column);
 402     }
 403 });