src/widgets/grid/Column.js

   1 /*!
   2  * Ext JS Library 3.2.0
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.grid.Column
   9  * <p>This class encapsulates column configuration data to be used in the initialization of a
  10  * {@link Ext.grid.ColumnModel ColumnModel}.</p>
  11  * <p>While subclasses are provided to render data in different ways, this class renders a passed
  12  * data field unchanged and is usually used for textual columns.</p>
  13  */
  14 Ext.grid.Column = Ext.extend(Object, {
  15     /**
  16      * @cfg {Boolean} editable Optional. Defaults to <tt>true</tt>, enabling the configured
  17      * <tt>{@link #editor}</tt>.  Set to <tt>false</tt> to initially disable editing on this column.
  18      * The initial configuration may be dynamically altered using
  19      * {@link Ext.grid.ColumnModel}.{@link Ext.grid.ColumnModel#setEditable setEditable()}.
  20      */
  21     /**
  22      * @cfg {String} id Optional. A name which identifies this column (defaults to the column's initial
  23      * ordinal position.) The <tt>id</tt> is used to create a CSS <b>class</b> name which is applied to all
  24      * table cells (including headers) in that column (in this context the <tt>id</tt> does not need to be
  25      * unique). The class name takes the form of <pre>x-grid3-td-<b>id</b></pre>
  26      * Header cells will also receive this class name, but will also have the class <pre>x-grid3-hd</pre>
  27      * So, to target header cells, use CSS selectors such as:<pre>.x-grid3-hd-row .x-grid3-td-<b>id</b></pre>
  28      * The {@link Ext.grid.GridPanel#autoExpandColumn} grid config option references the column via this
  29      * unique identifier.
  30      */
  31     /**
  32      * @cfg {String} header Optional. The header text to be used as innerHTML
  33      * (html tags are accepted) to display in the Grid view.  <b>Note</b>: to
  34      * have a clickable header with no text displayed use <tt>'&#160;'</tt>.
  35      */
  36     /**
  37      * @cfg {Boolean} groupable Optional. If the grid is being rendered by an {@link Ext.grid.GroupingView}, this option
  38      * may be used to disable the header menu item to group by the column selected. Defaults to <tt>true</tt>,
  39      * which enables the header menu group option.  Set to <tt>false</tt> to disable (but still show) the
  40      * group option in the header menu for the column. See also <code>{@link #groupName}</code>.
  41      */
  42     /**
  43      * @cfg {String} groupName Optional. If the grid is being rendered by an {@link Ext.grid.GroupingView}, this option
  44      * may be used to specify the text with which to prefix the group field value in the group header line.
  45      * See also {@link #groupRenderer} and
  46      * {@link Ext.grid.GroupingView}.{@link Ext.grid.GroupingView#showGroupName showGroupName}.
  47      */
  48     /**
  49      * @cfg {Function} groupRenderer <p>Optional. If the grid is being rendered by an {@link Ext.grid.GroupingView}, this option
  50      * may be used to specify the function used to format the grouping field value for display in the group
  51      * {@link #groupName header}.  If a <tt><b>groupRenderer</b></tt> is not specified, the configured
  52      * <tt><b>{@link #renderer}</b></tt> will be called; if a <tt><b>{@link #renderer}</b></tt> is also not specified
  53      * the new value of the group field will be used.</p>
  54      * <p>The called function (either the <tt><b>groupRenderer</b></tt> or <tt><b>{@link #renderer}</b></tt>) will be
  55      * passed the following parameters:
  56      * <div class="mdetail-params"><ul>
  57      * <li><b>v</b> : Object<p class="sub-desc">The new value of the group field.</p></li>
  58      * <li><b>unused</b> : undefined<p class="sub-desc">Unused parameter.</p></li>
  59      * <li><b>r</b> : Ext.data.Record<p class="sub-desc">The Record providing the data
  60      * for the row which caused group change.</p></li>
  61      * <li><b>rowIndex</b> : Number<p class="sub-desc">The row index of the Record which caused group change.</p></li>
  62      * <li><b>colIndex</b> : Number<p class="sub-desc">The column index of the group field.</p></li>
  63      * <li><b>ds</b> : Ext.data.Store<p class="sub-desc">The Store which is providing the data Model.</p></li>
  64      * </ul></div></p>
  65      * <p>The function should return a string value.</p>
  66      */
  67     /**
  68      * @cfg {String} emptyGroupText Optional. If the grid is being rendered by an {@link Ext.grid.GroupingView}, this option
  69      * may be used to specify the text to display when there is an empty group value. Defaults to the
  70      * {@link Ext.grid.GroupingView}.{@link Ext.grid.GroupingView#emptyGroupText emptyGroupText}.
  71      */
  72     /**
  73      * @cfg {String} dataIndex <p><b>Required</b>. The name of the field in the
  74      * grid's {@link Ext.data.Store}'s {@link Ext.data.Record} definition from
  75      * which to draw the column's value.</p>
  76      */
  77     /**
  78      * @cfg {Number} width
  79      * Optional. The initial width in pixels of the column.
  80      * The width of each column can also be affected if any of the following are configured:
  81      * <div class="mdetail-params"><ul>
  82      * <li>{@link Ext.grid.GridPanel}.<tt>{@link Ext.grid.GridPanel#autoExpandColumn autoExpandColumn}</tt></li>
  83      * <li>{@link Ext.grid.GridView}.<tt>{@link Ext.grid.GridView#forceFit forceFit}</tt>
  84      * <div class="sub-desc">
  85      * <p>By specifying <tt>forceFit:true</tt>, {@link #fixed non-fixed width} columns will be
  86      * re-proportioned (based on the relative initial widths) to fill the width of the grid so
  87      * that no horizontal scrollbar is shown.</p>
  88      * </div></li>
  89      * <li>{@link Ext.grid.GridView}.<tt>{@link Ext.grid.GridView#autoFill autoFill}</tt></li>
  90      * <li>{@link Ext.grid.GridPanel}.<tt>{@link Ext.grid.GridPanel#minColumnWidth minColumnWidth}</tt></li>
  91      * <br><p><b>Note</b>: when the width of each column is determined, a space on the right side
  92      * is reserved for the vertical scrollbar.  The
  93      * {@link Ext.grid.GridView}.<tt>{@link Ext.grid.GridView#scrollOffset scrollOffset}</tt>
  94      * can be modified to reduce or eliminate the reserved offset.</p>
  95      */
  96     /**
  97      * @cfg {Boolean} sortable Optional. <tt>true</tt> if sorting is to be allowed on this column.
  98      * Defaults to the value of the <code>{@link Ext.grid.ColumnModel#defaultSortable}</code> property.
  99      * Whether local/remote sorting is used is specified in <code>{@link Ext.data.Store#remoteSort}</code>.
 100      */
 101     /**
 102      * @cfg {Boolean} fixed Optional. <tt>true</tt> if the column width cannot be changed.  Defaults to <tt>false</tt>.
 103      */
 104     /**
 105      * @cfg {Boolean} resizable Optional. <tt>false</tt> to disable column resizing. Defaults to <tt>true</tt>.
 106      */
 107     /**
 108      * @cfg {Boolean} menuDisabled Optional. <tt>true</tt> to disable the column menu. Defaults to <tt>false</tt>.
 109      */
 110     /**
 111      * @cfg {Boolean} hidden
 112      * Optional. <tt>true</tt> to initially hide this column. Defaults to <tt>false</tt>.
 113      * A hidden column {@link Ext.grid.GridPanel#enableColumnHide may be shown via the header row menu}.
 114      * If a column is never to be shown, simply do not include this column in the Column Model at all.
 115      */
 116     /**
 117      * @cfg {String} tooltip Optional. A text string to use as the column header's tooltip.  If Quicktips
 118      * are enabled, this value will be used as the text of the quick tip, otherwise it will be set as the
 119      * header's HTML title attribute. Defaults to ''.
 120      */
 121     /**
 122      * @cfg {Mixed} renderer
 123      * <p>For an alternative to specifying a renderer see <code>{@link #xtype}</code></p>
 124      * <p>Optional. A renderer is an 'interceptor' method which can be used transform data (value,
 125      * appearance, etc.) before it is rendered). This may be specified in either of three ways:
 126      * <div class="mdetail-params"><ul>
 127      * <li>A renderer function used to return HTML markup for a cell given the cell's data value.</li>
 128      * <li>A string which references a property name of the {@link Ext.util.Format} class which
 129      * provides a renderer function.</li>
 130      * <li>An object specifying both the renderer function, and its execution scope (<tt><b>this</b></tt>
 131      * reference) e.g.:<pre style="margin-left:1.2em"><code>
 132 {
 133     fn: this.gridRenderer,
 134     scope: this
 135 }
 136 </code></pre></li></ul></div>
 137      * If not specified, the default renderer uses the raw data value.</p>
 138      * <p>For information about the renderer function (passed parameters, etc.), see
 139      * {@link Ext.grid.ColumnModel#setRenderer}. An example of specifying renderer function inline:</p><pre><code>
 140 var companyColumn = {
 141    header: 'Company Name',
 142    dataIndex: 'company',
 143    renderer: function(value, metaData, record, rowIndex, colIndex, store) {
 144       // provide the logic depending on business rules
 145       // name of your own choosing to manipulate the cell depending upon
 146       // the data in the underlying Record object.
 147       if (value == 'whatever') {
 148           //metaData.css : String : A CSS class name to add to the TD element of the cell.
 149           //metaData.attr : String : An html attribute definition string to apply to
 150           //                         the data container element within the table
 151           //                         cell (e.g. 'style="color:red;"').
 152           metaData.css = 'name-of-css-class-you-will-define';
 153       }
 154       return value;
 155    }
 156 }
 157      * </code></pre>
 158      * See also {@link #scope}.
 159      */
 160     /**
 161      * @cfg {String} xtype Optional. A String which references a predefined {@link Ext.grid.Column} subclass
 162      * type which is preconfigured with an appropriate <code>{@link #renderer}</code> to be easily
 163      * configured into a ColumnModel. The predefined {@link Ext.grid.Column} subclass types are:
 164      * <div class="mdetail-params"><ul>
 165      * <li><b><tt>gridcolumn</tt></b> : {@link Ext.grid.Column} (<b>Default</b>)<p class="sub-desc"></p></li>
 166      * <li><b><tt>booleancolumn</tt></b> : {@link Ext.grid.BooleanColumn}<p class="sub-desc"></p></li>
 167      * <li><b><tt>numbercolumn</tt></b> : {@link Ext.grid.NumberColumn}<p class="sub-desc"></p></li>
 168      * <li><b><tt>datecolumn</tt></b> : {@link Ext.grid.DateColumn}<p class="sub-desc"></p></li>
 169      * <li><b><tt>templatecolumn</tt></b> : {@link Ext.grid.TemplateColumn}<p class="sub-desc"></p></li>
 170      * </ul></div>
 171      * <p>Configuration properties for the specified <code>xtype</code> may be specified with
 172      * the Column configuration properties, for example:</p>
 173      * <pre><code>
 174 var grid = new Ext.grid.GridPanel({
 175     ...
 176     columns: [{
 177         header: 'Last Updated',
 178         dataIndex: 'lastChange',
 179         width: 85,
 180         sortable: true,
 181         //renderer: Ext.util.Format.dateRenderer('m/d/Y'),
 182         xtype: 'datecolumn', // use xtype instead of renderer
 183         format: 'M/d/Y' // configuration property for {@link Ext.grid.DateColumn}
 184     }, {
 185         ...
 186     }]
 187 });
 188      * </code></pre>
 189      */
 190     /**
 191      * @cfg {Object} scope Optional. The scope (<tt><b>this</b></tt> reference) in which to execute the
 192      * renderer.  Defaults to the Column configuration object.
 193      */
 194     /**
 195      * @cfg {String} align Optional. Set the CSS text-align property of the column.  Defaults to undefined.
 196      */
 197     /**
 198      * @cfg {String} css Optional. An inline style definition string which is applied to all table cells in the column
 199      * (excluding headers). Defaults to undefined.
 200      */
 201     /**
 202      * @cfg {Boolean} hideable Optional. Specify as <tt>false</tt> to prevent the user from hiding this column
 203      * (defaults to true).  To disallow column hiding globally for all columns in the grid, use
 204      * {@link Ext.grid.GridPanel#enableColumnHide} instead.
 205      */
 206     /**
 207      * @cfg {Ext.form.Field} editor Optional. The {@link Ext.form.Field} to use when editing values in this column
 208      * if editing is supported by the grid. See <tt>{@link #editable}</tt> also.
 209      */
 210
 211     /**
 212      * @private
 213      * @cfg {Boolean} isColumn
 214      * Used by ColumnModel setConfig method to avoid reprocessing a Column
 215      * if <code>isColumn</code> is not set ColumnModel will recreate a new Ext.grid.Column
 216      * Defaults to true.
 217      */
 218     isColumn : true,
 219
 220     constructor : function(config){
 221         Ext.apply(this, config);
 222
 223         if(Ext.isString(this.renderer)){
 224             this.renderer = Ext.util.Format[this.renderer];
 225         }else if(Ext.isObject(this.renderer)){
 226             this.scope = this.renderer.scope;
 227             this.renderer = this.renderer.fn;
 228         }
 229         if(!this.scope){
 230             this.scope = this;
 231         }
 232
 233         var ed = this.editor;
 234         delete this.editor;
 235         this.setEditor(ed);
 236     },
 237
 238     /**
 239      * Optional. A function which returns displayable data when passed the following parameters:
 240      * <div class="mdetail-params"><ul>
 241      * <li><b>value</b> : Object<p class="sub-desc">The data value for the cell.</p></li>
 242      * <li><b>metadata</b> : Object<p class="sub-desc">An object in which you may set the following attributes:<ul>
 243      * <li><b>css</b> : String<p class="sub-desc">A CSS class name to add to the cell's TD element.</p></li>
 244      * <li><b>attr</b> : String<p class="sub-desc">An HTML attribute definition string to apply to the data container
 245      * element <i>within</i> the table cell (e.g. 'style="color:red;"').</p></li></ul></p></li>
 246      * <li><b>record</b> : Ext.data.record<p class="sub-desc">The {@link Ext.data.Record} from which the data was
 247      * extracted.</p></li>
 248      * <li><b>rowIndex</b> : Number<p class="sub-desc">Row index</p></li>
 249      * <li><b>colIndex</b> : Number<p class="sub-desc">Column index</p></li>
 250      * <li><b>store</b> : Ext.data.Store<p class="sub-desc">The {@link Ext.data.Store} object from which the Record
 251      * was extracted.</p></li>
 252      * </ul></div>
 253      * @property renderer
 254      * @type Function
 255      */
 256     renderer : function(value){
 257         if(Ext.isString(value) && value.length < 1){
 258             return '&#160;';
 259         }
 260         return value;
 261     },
 262
 263     // private
 264     getEditor: function(rowIndex){
 265         return this.editable !== false ? this.editor : null;
 266     },
 267
 268     /**
 269      * Sets a new editor for this column.
 270      * @param {Ext.Editor/Ext.form.Field} editor The editor to set
 271      */
 272     setEditor : function(editor){
 273         var ed = this.editor;
 274         if(ed){
 275             if(ed.gridEditor){
 276                 ed.gridEditor.destroy();
 277                 delete ed.gridEditor;
 278             }else{
 279                 ed.destroy();
 280             }
 281         }
 282         this.editor = null;
 283         if(editor){
 284             //not an instance, create it
 285             if(!editor.isXType){
 286                 editor = Ext.create(editor, 'textfield');
 287             }
 288             this.editor = editor;
 289         }
 290     },
 291
 292     /**
 293      * Returns the {@link Ext.Editor editor} defined for this column that was created to wrap the {@link Ext.form.Field Field}
 294      * used to edit the cell.
 295      * @param {Number} rowIndex The row index
 296      * @return {Ext.Editor}
 297      */
 298     getCellEditor: function(rowIndex){
 299         var ed = this.getEditor(rowIndex);
 300         if(ed){
 301             if(!ed.startEdit){
 302                 if(!ed.gridEditor){
 303                     ed.gridEditor = new Ext.grid.GridEditor(ed);
 304                 }
 305                 ed = ed.gridEditor;
 306             }
 307         }
 308         return ed;
 309     }
 310 });
 311
 312 /**
 313  * @class Ext.grid.BooleanColumn
 314  * @extends Ext.grid.Column
 315  * <p>A Column definition class which renders boolean data fields.  See the {@link Ext.grid.Column#xtype xtype}
 316  * config option of {@link Ext.grid.Column} for more details.</p>
 317  */
 318 Ext.grid.BooleanColumn = Ext.extend(Ext.grid.Column, {
 319     /**
 320      * @cfg {String} trueText
 321      * The string returned by the renderer when the column value is not falsey (defaults to <tt>'true'</tt>).
 322      */
 323     trueText: 'true',
 324     /**
 325      * @cfg {String} falseText
 326      * The string returned by the renderer when the column value is falsey (but not undefined) (defaults to
 327      * <tt>'false'</tt>).
 328      */
 329     falseText: 'false',
 330     /**
 331      * @cfg {String} undefinedText
 332      * The string returned by the renderer when the column value is undefined (defaults to <tt>'&#160;'</tt>).
 333      */
 334     undefinedText: '&#160;',
 335
 336     constructor: function(cfg){
 337         Ext.grid.BooleanColumn.superclass.constructor.call(this, cfg);
 338         var t = this.trueText, f = this.falseText, u = this.undefinedText;
 339         this.renderer = function(v){
 340             if(v === undefined){
 341                 return u;
 342             }
 343             if(!v || v === 'false'){
 344                 return f;
 345             }
 346             return t;
 347         };
 348     }
 349 });
 350
 351 /**
 352  * @class Ext.grid.NumberColumn
 353  * @extends Ext.grid.Column
 354  * <p>A Column definition class which renders a numeric data field according to a {@link #format} string.  See the
 355  * {@link Ext.grid.Column#xtype xtype} config option of {@link Ext.grid.Column} for more details.</p>
 356  */
 357 Ext.grid.NumberColumn = Ext.extend(Ext.grid.Column, {
 358     /**
 359      * @cfg {String} format
 360      * A formatting string as used by {@link Ext.util.Format#number} to format a numeric value for this Column
 361      * (defaults to <tt>'0,000.00'</tt>).
 362      */
 363     format : '0,000.00',
 364     constructor: function(cfg){
 365         Ext.grid.NumberColumn.superclass.constructor.call(this, cfg);
 366         this.renderer = Ext.util.Format.numberRenderer(this.format);
 367     }
 368 });
 369
 370 /**
 371  * @class Ext.grid.DateColumn
 372  * @extends Ext.grid.Column
 373  * <p>A Column definition class which renders a passed date according to the default locale, or a configured
 374  * {@link #format}. See the {@link Ext.grid.Column#xtype xtype} config option of {@link Ext.grid.Column}
 375  * for more details.</p>
 376  */
 377 Ext.grid.DateColumn = Ext.extend(Ext.grid.Column, {
 378     /**
 379      * @cfg {String} format
 380      * A formatting string as used by {@link Date#format} to format a Date for this Column
 381      * (defaults to <tt>'m/d/Y'</tt>).
 382      */
 383     format : 'm/d/Y',
 384     constructor: function(cfg){
 385         Ext.grid.DateColumn.superclass.constructor.call(this, cfg);
 386         this.renderer = Ext.util.Format.dateRenderer(this.format);
 387     }
 388 });
 389
 390 /**
 391  * @class Ext.grid.TemplateColumn
 392  * @extends Ext.grid.Column
 393  * <p>A Column definition class which renders a value by processing a {@link Ext.data.Record Record}'s
 394  * {@link Ext.data.Record#data data} using a {@link #tpl configured} {@link Ext.XTemplate XTemplate}.
 395  * See the {@link Ext.grid.Column#xtype xtype} config option of {@link Ext.grid.Column} for more
 396  * details.</p>
 397  */
 398 Ext.grid.TemplateColumn = Ext.extend(Ext.grid.Column, {
 399     /**
 400      * @cfg {String/XTemplate} tpl
 401      * An {@link Ext.XTemplate XTemplate}, or an XTemplate <i>definition string</i> to use to process a
 402      * {@link Ext.data.Record Record}'s {@link Ext.data.Record#data data} to produce a column's rendered value.
 403      */
 404     constructor: function(cfg){
 405         Ext.grid.TemplateColumn.superclass.constructor.call(this, cfg);
 406         var tpl = (!Ext.isPrimitive(this.tpl) && this.tpl.compile) ? this.tpl : new Ext.XTemplate(this.tpl);
 407         this.renderer = function(value, p, r){
 408             return tpl.apply(r.data);
 409         };
 410         this.tpl = tpl;
 411     }
 412 });
 413
 414 /*
 415  * @property types
 416  * @type Object
 417  * @member Ext.grid.Column
 418  * @static
 419  * <p>An object containing predefined Column classes keyed by a mnemonic code which may be referenced
 420  * by the {@link Ext.grid.ColumnModel#xtype xtype} config option of ColumnModel.</p>
 421  * <p>This contains the following properties</p><div class="mdesc-details"><ul>
 422  * <li>gridcolumn : <b>{@link Ext.grid.Column Column constructor}</b></li>
 423  * <li>booleancolumn : <b>{@link Ext.grid.BooleanColumn BooleanColumn constructor}</b></li>
 424  * <li>numbercolumn : <b>{@link Ext.grid.NumberColumn NumberColumn constructor}</b></li>
 425  * <li>datecolumn : <b>{@link Ext.grid.DateColumn DateColumn constructor}</b></li>
 426  * <li>templatecolumn : <b>{@link Ext.grid.TemplateColumn TemplateColumn constructor}</b></li>
 427  * </ul></div>
 428  */
 429 Ext.grid.Column.types = {
 430     gridcolumn : Ext.grid.Column,
 431     booleancolumn: Ext.grid.BooleanColumn,
 432     numbercolumn: Ext.grid.NumberColumn,
 433     datecolumn: Ext.grid.DateColumn,
 434     templatecolumn: Ext.grid.TemplateColumn
 435 };