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