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