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