src/grid/column/Action.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  * A Grid header type which renders an icon, or a series of icons in a grid cell, and offers a scoped click
  17  * handler for each icon.
  18  *
  19  *     @example
  20  *     Ext.create('Ext.data.Store', {
  21  *         storeId:'employeeStore',
  22  *         fields:['firstname', 'lastname', 'senority', 'dep', 'hired'],
  23  *         data:[
  24  *             {firstname:"Michael", lastname:"Scott"},
  25  *             {firstname:"Dwight", lastname:"Schrute"},
  26  *             {firstname:"Jim", lastname:"Halpert"},
  27  *             {firstname:"Kevin", lastname:"Malone"},
  28  *             {firstname:"Angela", lastname:"Martin"}
  29  *         ]
  30  *     });
  31  *
  32  *     Ext.create('Ext.grid.Panel', {
  33  *         title: 'Action Column Demo',
  34  *         store: Ext.data.StoreManager.lookup('employeeStore'),
  35  *         columns: [
  36  *             {text: 'First Name',  dataIndex:'firstname'},
  37  *             {text: 'Last Name',  dataIndex:'lastname'},
  38  *             {
  39  *                 xtype:'actioncolumn',
  40  *                 width:50,
  41  *                 items: [{
  42  *                     icon: 'extjs/examples/shared/icons/fam/cog_edit.png',  // Use a URL in the icon config
  43  *                     tooltip: 'Edit',
  44  *                     handler: function(grid, rowIndex, colIndex) {
  45  *                         var rec = grid.getStore().getAt(rowIndex);
  46  *                         alert("Edit " + rec.get('firstname'));
  47  *                     }
  48  *                 },{
  49  *                     icon: 'extjs/examples/restful/images/delete.png',
  50  *                     tooltip: 'Delete',
  51  *                     handler: function(grid, rowIndex, colIndex) {
  52  *                         var rec = grid.getStore().getAt(rowIndex);
  53  *                         alert("Terminate " + rec.get('firstname'));
  54  *                     }
  55  *                 }]
  56  *             }
  57  *         ],
  58  *         width: 250,
  59  *         renderTo: Ext.getBody()
  60  *     });
  61  *
  62  * The action column can be at any index in the columns array, and a grid can have any number of
  63  * action columns.
  64  */
  65 Ext.define('Ext.grid.column.Action', {
  66     extend: 'Ext.grid.column.Column',
  67     alias: ['widget.actioncolumn'],
  68     alternateClassName: 'Ext.grid.ActionColumn',
  69
  70     /**
  71      * @cfg {String} icon
  72      * The URL of an image to display as the clickable element in the column. Defaults to
  73      * `{@link Ext#BLANK_IMAGE_URL Ext.BLANK_IMAGE_URL}`.
  74      */
  75     /**
  76      * @cfg {String} iconCls
  77      * A CSS class to apply to the icon image. To determine the class dynamically, configure the Column with
  78      * a `{@link #getClass}` function.
  79      */
  80     /**
  81      * @cfg {Function} handler
  82      * A function called when the icon is clicked.
  83      * @cfg {Ext.view.Table} handler.view The owning TableView.
  84      * @cfg {Number} handler.rowIndex The row index clicked on.
  85      * @cfg {Number} handler.colIndex The column index clicked on.
  86      * @cfg {Object} handler.item The clicked item (or this Column if multiple {@link #items} were not configured).
  87      * @cfg {Event} handler.e The click event.
  88      */
  89     /**
  90      * @cfg {Object} scope
  91      * The scope (**this** reference) in which the `{@link #handler}` and `{@link #getClass}` fuctions are executed.
  92      * Defaults to this Column.
  93      */
  94     /**
  95      * @cfg {String} tooltip
  96      * A tooltip message to be displayed on hover. {@link Ext.tip.QuickTipManager#init Ext.tip.QuickTipManager} must
  97      * have been initialized.
  98      */
  99     /* @cfg {Boolean} disabled
 100      * If true, the action will not respond to click events, and will be displayed semi-opaque.
 101      */
 102     /**
 103      * @cfg {Boolean} [stopSelection=true]
 104      * Prevent grid _row_ selection upon mousedown.
 105      */
 106     /**
 107      * @cfg {Function} getClass
 108      * A function which returns the CSS class to apply to the icon image.
 109      *
 110      * @cfg {Object} getClass.v The value of the column's configured field (if any).
 111      *
 112      * @cfg {Object} getClass.metadata An object in which you may set the following attributes:
 113      * @cfg {String} getClass.metadata.css A CSS class name to add to the cell's TD element.
 114      * @cfg {String} getClass.metadata.attr An HTML attribute definition string to apply to the data container
 115      * element *within* the table cell (e.g. 'style="color:red;"').
 116      *
 117      * @cfg {Ext.data.Model} getClass.r The Record providing the data.
 118      *
 119      * @cfg {Number} getClass.rowIndex The row index..
 120      *
 121      * @cfg {Number} getClass.colIndex The column index.
 122      *
 123      * @cfg {Ext.data.Store} getClass.store The Store which is providing the data Model.
 124      */
 125     /**
 126      * @cfg {Object[]} items
 127      * An Array which may contain multiple icon definitions, each element of which may contain:
 128      *
 129      * @cfg {String} items.icon The url of an image to display as the clickable element in the column.
 130      *
 131      * @cfg {String} items.iconCls A CSS class to apply to the icon image. To determine the class dynamically,
 132      * configure the item with a `getClass` function.
 133      *
 134      * @cfg {Function} items.getClass A function which returns the CSS class to apply to the icon image.
 135      * @cfg {Object} items.getClass.v The value of the column's configured field (if any).
 136      * @cfg {Object} items.getClass.metadata An object in which you may set the following attributes:
 137      * @cfg {String} items.getClass.metadata.css A CSS class name to add to the cell's TD element.
 138      * @cfg {String} items.getClass.metadata.attr An HTML attribute definition string to apply to the data
 139      * container element _within_ the table cell (e.g. 'style="color:red;"').
 140      * @cfg {Ext.data.Model} items.getClass.r The Record providing the data.
 141      * @cfg {Number} items.getClass.rowIndex The row index..
 142      * @cfg {Number} items.getClass.colIndex The column index.
 143      * @cfg {Ext.data.Store} items.getClass.store The Store which is providing the data Model.
 144      *
 145      * @cfg {Function} items.handler A function called when the icon is clicked.
 146      *
 147      * @cfg {Object} items.scope The scope (`this` reference) in which the `handler` and `getClass` functions
 148      * are executed. Fallback defaults are this Column's configured scope, then this Column.
 149      *
 150      * @cfg {String} items.tooltip A tooltip message to be displayed on hover.
 151      * @cfg {Boolean} items.disabled If true, the action will not respond to click events, and will be displayed semi-opaque.
 152      * {@link Ext.tip.QuickTipManager#init Ext.tip.QuickTipManager} must have been initialized.
 153      */
 154     /**
 155      * @property {Array} items
 156      * An array of action items copied from the configured {@link #cfg-items items} configuration. Each will have
 157      * an `enable` and `disable` method added which will enable and disable the associated action, and
 158      * update the displayed icon accordingly.
 159      */
 160     header: '&#160;',
 161
 162     actionIdRe: new RegExp(Ext.baseCSSPrefix + 'action-col-(\\d+)'),
 163
 164     /**
 165      * @cfg {String} altText
 166      * The alt text to use for the image element.
 167      */
 168     altText: '',
 169
 170     sortable: false,
 171
 172     constructor: function(config) {
 173         var me = this,
 174             cfg = Ext.apply({}, config),
 175             items = cfg.items || [me],
 176             l = items.length,
 177             i,
 178             item;
 179
 180         // This is a Container. Delete the items config to be reinstated after construction.
 181         delete cfg.items;
 182         me.callParent([cfg]);
 183
 184         // Items is an array property of ActionColumns
 185         me.items = items;
 186
 187 //      Renderer closure iterates through items creating an <img> element for each and tagging with an identifying
 188 //      class name x-action-col-{n}
 189         me.renderer = function(v, meta) {
 190 //          Allow a configured renderer to create initial value (And set the other values in the "metadata" argument!)
 191             v = Ext.isFunction(cfg.renderer) ? cfg.renderer.apply(this, arguments)||'' : '';
 192
 193             meta.tdCls += ' ' + Ext.baseCSSPrefix + 'action-col-cell';
 194             for (i = 0; i < l; i++) {
 195                 item = items[i];
 196                 item.disable = Ext.Function.bind(me.disableAction, me, [i]);
 197                 item.enable = Ext.Function.bind(me.enableAction, me, [i]);
 198                 v += '<img alt="' + (item.altText || me.altText) + '" src="' + (item.icon || Ext.BLANK_IMAGE_URL) +
 199                     '" class="' + Ext.baseCSSPrefix + 'action-col-icon ' + Ext.baseCSSPrefix + 'action-col-' + String(i) + ' ' + (item.disabled ? Ext.baseCSSPrefix + 'item-disabled' : ' ') + (item.iconCls || '') +
 200                     ' ' + (Ext.isFunction(item.getClass) ? item.getClass.apply(item.scope||me.scope||me, arguments) : (me.iconCls || '')) + '"' +
 201                     ((item.tooltip) ? ' data-qtip="' + item.tooltip + '"' : '') + ' />';
 202             }
 203             return v;
 204         };
 205     },
 206
 207     /**
 208      * Enables this ActionColumn's action at the specified index.
 209      */
 210     enableAction: function(index) {
 211         var me = this;
 212
 213         if (!index) {
 214             index = 0;
 215         } else if (!Ext.isNumber(index)) {
 216             index = Ext.Array.indexOf(me.items, index);
 217         }
 218         me.items[index].disabled = false;
 219         me.up('tablepanel').el.select('.' + Ext.baseCSSPrefix + 'action-col-' + index).removeCls(me.disabledCls);
 220     },
 221
 222     /**
 223      * Disables this ActionColumn's action at the specified index.
 224      */
 225     disableAction: function(index) {
 226         var me = this;
 227
 228         if (!index) {
 229             index = 0;
 230         } else if (!Ext.isNumber(index)) {
 231             index = Ext.Array.indexOf(me.items, index);
 232         }
 233         me.items[index].disabled = true;
 234         me.up('tablepanel').el.select('.' + Ext.baseCSSPrefix + 'action-col-' + index).addCls(me.disabledCls);
 235     },
 236
 237     destroy: function() {
 238         delete this.items;
 239         delete this.renderer;
 240         return this.callParent(arguments);
 241     },
 242
 243     /**
 244      * @private
 245      * Process and refire events routed from the GridView's processEvent method.
 246      * Also fires any configured click handlers. By default, cancels the mousedown event to prevent selection.
 247      * Returns the event handler's status to allow canceling of GridView's bubbling process.
 248      */
 249     processEvent : function(type, view, cell, recordIndex, cellIndex, e){
 250         var me = this,
 251             match = e.getTarget().className.match(me.actionIdRe),
 252             item, fn;
 253
 254         if (match) {
 255             item = me.items[parseInt(match[1], 10)];
 256             if (item) {
 257                 if (type == 'click') {
 258                     fn = item.handler || me.handler;
 259                     if (fn && !item.disabled) {
 260                         fn.call(item.scope || me.scope || me, view, recordIndex, cellIndex, item, e);
 261                     }
 262                 } else if (type == 'mousedown' && item.stopSelection !== false) {
 263                     return false;
 264                 }
 265             }
 266         }
 267         return me.callParent(arguments);
 268     },
 269
 270     cascade: function(fn, scope) {
 271         fn.call(scope||this, this);
 272     },
 273
 274     // Private override because this cannot function as a Container, and it has an items property which is an Array, NOT a MixedCollection.
 275     getRefItems: function() {
 276         return [];
 277     }
 278 });