Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / PropertyGrid.html
1 <html>\r
2 <head>\r
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
4   <title>The source code</title>\r
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
7 </head>\r
8 <body  onload="prettyPrint();">\r
9     <pre class="prettyprint lang-js"><div id="cls-Ext.grid.PropertyRecord"></div>/**
10  * @class Ext.grid.PropertyRecord
11  * A specific {@link Ext.data.Record} type that represents a name/value pair and is made to work with the
12  * {@link Ext.grid.PropertyGrid}.  Typically, PropertyRecords do not need to be created directly as they can be
13  * created implicitly by simply using the appropriate data configs either via the {@link Ext.grid.PropertyGrid#source}
14  * config property or by calling {@link Ext.grid.PropertyGrid#setSource}.  However, if the need arises, these records
15  * can also be created explicitly as shwon below.  Example usage:
16  * <pre><code>
17 var rec = new Ext.grid.PropertyRecord({
18     name: 'Birthday',
19     value: new Date(Date.parse('05/26/1972'))
20 });
21 // Add record to an already populated grid
22 grid.store.addSorted(rec);
23 </code></pre>
24  * @constructor
25  * @param {Object} config A data object in the format: {name: [name], value: [value]}.  The specified value's type
26  * will be read automatically by the grid to determine the type of editor to use when displaying it.
27  */
28 Ext.grid.PropertyRecord = Ext.data.Record.create([
29     {name:'name',type:'string'}, 'value'
30 ]);
31
32 <div id="cls-Ext.grid.PropertyStore"></div>/**
33  * @class Ext.grid.PropertyStore
34  * @extends Ext.util.Observable
35  * A custom wrapper for the {@link Ext.grid.PropertyGrid}'s {@link Ext.data.Store}. This class handles the mapping
36  * between the custom data source objects supported by the grid and the {@link Ext.grid.PropertyRecord} format
37  * required for compatibility with the underlying store. Generally this class should not need to be used directly --
38  * the grid's data should be accessed from the underlying store via the {@link #store} property.
39  * @constructor
40  * @param {Ext.grid.Grid} grid The grid this store will be bound to
41  * @param {Object} source The source data config object
42  */
43 Ext.grid.PropertyStore = Ext.extend(Ext.util.Observable, {
44     
45     constructor : function(grid, source){
46         this.grid = grid;
47         this.store = new Ext.data.Store({
48             recordType : Ext.grid.PropertyRecord
49         });
50         this.store.on('update', this.onUpdate,  this);
51         if(source){
52             this.setSource(source);
53         }
54         Ext.grid.PropertyStore.superclass.constructor.call(this);    
55     },
56     
57     // protected - should only be called by the grid.  Use grid.setSource instead.
58     setSource : function(o){
59         this.source = o;
60         this.store.removeAll();
61         var data = [];
62         for(var k in o){
63             if(this.isEditableValue(o[k])){
64                 data.push(new Ext.grid.PropertyRecord({name: k, value: o[k]}, k));
65             }
66         }
67         this.store.loadRecords({records: data}, {}, true);
68     },
69
70     // private
71     onUpdate : function(ds, record, type){
72         if(type == Ext.data.Record.EDIT){
73             var v = record.data.value;
74             var oldValue = record.modified.value;
75             if(this.grid.fireEvent('beforepropertychange', this.source, record.id, v, oldValue) !== false){
76                 this.source[record.id] = v;
77                 record.commit();
78                 this.grid.fireEvent('propertychange', this.source, record.id, v, oldValue);
79             }else{
80                 record.reject();
81             }
82         }
83     },
84
85     // private
86     getProperty : function(row){
87        return this.store.getAt(row);
88     },
89
90     // private
91     isEditableValue: function(val){
92         return Ext.isPrimitive(val) || Ext.isDate(val);
93     },
94
95     // private
96     setValue : function(prop, value){
97         this.source[prop] = value;
98         this.store.getById(prop).set('value', value);
99     },
100
101     // protected - should only be called by the grid.  Use grid.getSource instead.
102     getSource : function(){
103         return this.source;
104     }
105 });
106
107 <div id="cls-Ext.grid.PropertyColumnModel"></div>/**
108  * @class Ext.grid.PropertyColumnModel
109  * @extends Ext.grid.ColumnModel
110  * A custom column model for the {@link Ext.grid.PropertyGrid}.  Generally it should not need to be used directly.
111  * @constructor
112  * @param {Ext.grid.Grid} grid The grid this store will be bound to
113  * @param {Object} source The source data config object
114  */
115 Ext.grid.PropertyColumnModel = Ext.extend(Ext.grid.ColumnModel, {
116     // private - strings used for locale support
117     nameText : 'Name',
118     valueText : 'Value',
119     dateFormat : 'm/j/Y',
120     
121     constructor : function(grid, store){
122         var g = Ext.grid,
123                 f = Ext.form;
124                 
125             this.grid = grid;
126             g.PropertyColumnModel.superclass.constructor.call(this, [
127                 {header: this.nameText, width:50, sortable: true, dataIndex:'name', id: 'name', menuDisabled:true},
128                 {header: this.valueText, width:50, resizable:false, dataIndex: 'value', id: 'value', menuDisabled:true}
129             ]);
130             this.store = store;
131         
132             var bfield = new f.Field({
133                 autoCreate: {tag: 'select', children: [
134                     {tag: 'option', value: 'true', html: 'true'},
135                     {tag: 'option', value: 'false', html: 'false'}
136                 ]},
137                 getValue : function(){
138                     return this.el.dom.value == 'true';
139                 }
140             });
141             this.editors = {
142                 'date' : new g.GridEditor(new f.DateField({selectOnFocus:true})),
143                 'string' : new g.GridEditor(new f.TextField({selectOnFocus:true})),
144                 'number' : new g.GridEditor(new f.NumberField({selectOnFocus:true, style:'text-align:left;'})),
145                 'boolean' : new g.GridEditor(bfield, {
146                     autoSize: 'both'
147                 })
148             };
149             this.renderCellDelegate = this.renderCell.createDelegate(this);
150             this.renderPropDelegate = this.renderProp.createDelegate(this);
151     },
152
153     // private
154     renderDate : function(dateVal){
155         return dateVal.dateFormat(this.dateFormat);
156     },
157
158     // private
159     renderBool : function(bVal){
160         return bVal ? 'true' : 'false';
161     },
162
163     // private
164     isCellEditable : function(colIndex, rowIndex){
165         return colIndex == 1;
166     },
167
168     // private
169     getRenderer : function(col){
170         return col == 1 ?
171             this.renderCellDelegate : this.renderPropDelegate;
172     },
173
174     // private
175     renderProp : function(v){
176         return this.getPropertyName(v);
177     },
178
179     // private
180     renderCell : function(val){
181         var rv = val;
182         if(Ext.isDate(val)){
183             rv = this.renderDate(val);
184         }else if(typeof val == 'boolean'){
185             rv = this.renderBool(val);
186         }
187         return Ext.util.Format.htmlEncode(rv);
188     },
189
190     // private
191     getPropertyName : function(name){
192         var pn = this.grid.propertyNames;
193         return pn && pn[name] ? pn[name] : name;
194     },
195
196     // private
197     getCellEditor : function(colIndex, rowIndex){
198         var p = this.store.getProperty(rowIndex),
199             n = p.data.name, 
200             val = p.data.value;
201         if(this.grid.customEditors[n]){
202             return this.grid.customEditors[n];
203         }
204         if(Ext.isDate(val)){
205             return this.editors.date;
206         }else if(typeof val == 'number'){
207             return this.editors.number;
208         }else if(typeof val == 'boolean'){
209             return this.editors['boolean'];
210         }else{
211             return this.editors.string;
212         }
213     },
214
215     // inherit docs
216     destroy : function(){
217         Ext.grid.PropertyColumnModel.superclass.destroy.call(this);
218         for(var ed in this.editors){
219             Ext.destroy(this.editors[ed]);
220         }
221     }
222 });
223
224 <div id="cls-Ext.grid.PropertyGrid"></div>/**
225  * @class Ext.grid.PropertyGrid
226  * @extends Ext.grid.EditorGridPanel
227  * A specialized grid implementation intended to mimic the traditional property grid as typically seen in
228  * development IDEs.  Each row in the grid represents a property of some object, and the data is stored
229  * as a set of name/value pairs in {@link Ext.grid.PropertyRecord}s.  Example usage:
230  * <pre><code>
231 var grid = new Ext.grid.PropertyGrid({
232     title: 'Properties Grid',
233     autoHeight: true,
234     width: 300,
235     renderTo: 'grid-ct',
236     source: {
237         "(name)": "My Object",
238         "Created": new Date(Date.parse('10/15/2006')),
239         "Available": false,
240         "Version": .01,
241         "Description": "A test object"
242     }
243 });
244 </code></pre>
245  * @constructor
246  * @param {Object} config The grid config object
247  */
248 Ext.grid.PropertyGrid = Ext.extend(Ext.grid.EditorGridPanel, {
249     <div id="cfg-Ext.grid.PropertyGrid-propertyNames"></div>/**
250     * @cfg {Object} propertyNames An object containing property name/display name pairs.
251     * If specified, the display name will be shown in the name column instead of the property name.
252     */
253     <div id="cfg-Ext.grid.PropertyGrid-source"></div>/**
254     * @cfg {Object} source A data object to use as the data source of the grid (see {@link #setSource} for details).
255     */
256     <div id="cfg-Ext.grid.PropertyGrid-customEditors"></div>/**
257     * @cfg {Object} customEditors An object containing name/value pairs of custom editor type definitions that allow
258     * the grid to support additional types of editable fields.  By default, the grid supports strongly-typed editing
259     * of strings, dates, numbers and booleans using built-in form editors, but any custom type can be supported and
260     * associated with a custom input control by specifying a custom editor.  The name of the editor
261     * type should correspond with the name of the property that will use the editor.  Example usage:
262     * <pre><code>
263 var grid = new Ext.grid.PropertyGrid({
264     ...
265     customEditors: {
266         'Start Time': new Ext.grid.GridEditor(new Ext.form.TimeField({selectOnFocus:true}))
267     },
268     source: {
269         'Start Time': '10:00 AM'
270     }
271 });
272 </code></pre>
273     */
274
275     // private config overrides
276     enableColumnMove:false,
277     stripeRows:false,
278     trackMouseOver: false,
279     clicksToEdit:1,
280     enableHdMenu : false,
281     viewConfig : {
282         forceFit:true
283     },
284
285     // private
286     initComponent : function(){
287         this.customEditors = this.customEditors || {};
288         this.lastEditRow = null;
289         var store = new Ext.grid.PropertyStore(this);
290         this.propStore = store;
291         var cm = new Ext.grid.PropertyColumnModel(this, store);
292         store.store.sort('name', 'ASC');
293         this.addEvents(
294             <div id="event-Ext.grid.PropertyGrid-beforepropertychange"></div>/**
295              * @event beforepropertychange
296              * Fires before a property value changes.  Handlers can return false to cancel the property change
297              * (this will internally call {@link Ext.data.Record#reject} on the property's record).
298              * @param {Object} source The source data object for the grid (corresponds to the same object passed in
299              * as the {@link #source} config property).
300              * @param {String} recordId The record's id in the data store
301              * @param {Mixed} value The current edited property value
302              * @param {Mixed} oldValue The original property value prior to editing
303              */
304             'beforepropertychange',
305             <div id="event-Ext.grid.PropertyGrid-propertychange"></div>/**
306              * @event propertychange
307              * Fires after a property value has changed.
308              * @param {Object} source The source data object for the grid (corresponds to the same object passed in
309              * as the {@link #source} config property).
310              * @param {String} recordId The record's id in the data store
311              * @param {Mixed} value The current edited property value
312              * @param {Mixed} oldValue The original property value prior to editing
313              */
314             'propertychange'
315         );
316         this.cm = cm;
317         this.ds = store.store;
318         Ext.grid.PropertyGrid.superclass.initComponent.call(this);
319
320                 this.mon(this.selModel, 'beforecellselect', function(sm, rowIndex, colIndex){
321             if(colIndex === 0){
322                 this.startEditing.defer(200, this, [rowIndex, 1]);
323                 return false;
324             }
325         }, this);
326     },
327
328     // private
329     onRender : function(){
330         Ext.grid.PropertyGrid.superclass.onRender.apply(this, arguments);
331
332         this.getGridEl().addClass('x-props-grid');
333     },
334
335     // private
336     afterRender: function(){
337         Ext.grid.PropertyGrid.superclass.afterRender.apply(this, arguments);
338         if(this.source){
339             this.setSource(this.source);
340         }
341     },
342
343     <div id="method-Ext.grid.PropertyGrid-setSource"></div>/**
344      * Sets the source data object containing the property data.  The data object can contain one or more name/value
345      * pairs representing all of the properties of an object to display in the grid, and this data will automatically
346      * be loaded into the grid's {@link #store}.  The values should be supplied in the proper data type if needed,
347      * otherwise string type will be assumed.  If the grid already contains data, this method will replace any
348      * existing data.  See also the {@link #source} config value.  Example usage:
349      * <pre><code>
350 grid.setSource({
351     "(name)": "My Object",
352     "Created": new Date(Date.parse('10/15/2006')),  // date type
353     "Available": false,  // boolean type
354     "Version": .01,      // decimal type
355     "Description": "A test object"
356 });
357 </code></pre>
358      * @param {Object} source The data object
359      */
360     setSource : function(source){
361         this.propStore.setSource(source);
362     },
363
364     <div id="method-Ext.grid.PropertyGrid-getSource"></div>/**
365      * Gets the source data object containing the property data.  See {@link #setSource} for details regarding the
366      * format of the data object.
367      * @return {Object} The data object
368      */
369     getSource : function(){
370         return this.propStore.getSource();
371     }
372
373     <div id="cfg-Ext.grid.PropertyGrid-null"></div>/**
374      * @cfg store
375      * @hide
376      */
377     <div id="cfg-Ext.grid.PropertyGrid-null"></div>/**
378      * @cfg colModel
379      * @hide
380      */
381     <div id="cfg-Ext.grid.PropertyGrid-null"></div>/**
382      * @cfg cm
383      * @hide
384      */
385     <div id="cfg-Ext.grid.PropertyGrid-null"></div>/**
386      * @cfg columns
387      * @hide
388      */
389 });
390 Ext.reg("propertygrid", Ext.grid.PropertyGrid);
391 </pre>    \r
392 </body>\r
393 </html>