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