src/widgets/grid/Column.js

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