Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / Record.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.data.Record"></div>/**
16  * @class Ext.data.Record
17  * <p>Instances of this class encapsulate both Record <em>definition</em> information, and Record
18  * <em>value</em> information for use in {@link Ext.data.Store} objects, or any code which needs
19  * to access Records cached in an {@link Ext.data.Store} object.</p>
20  * <p>Constructors for this class are generated by passing an Array of field definition objects to {@link #create}.
21  * Instances are usually only created by {@link Ext.data.Reader} implementations when processing unformatted data
22  * objects.</p>
23  * <p>Note that an instance of a Record class may only belong to one {@link Ext.data.Store Store} at a time.
24  * In order to copy data from one Store to another, use the {@link #copy} method to create an exact
25  * copy of the Record, and insert the new instance into the other Store.</p>
26  * <p>When serializing a Record for submission to the server, be aware that it contains many private
27  * properties, and also a reference to its owning Store which in turn holds references to its Records.
28  * This means that a whole Record may not be encoded using {@link Ext.util.JSON.encode}. Instead, use the
29  * <code>{@link #data}</code> and <code>{@link #id}</code> properties.</p>
30  * <p>Record objects generated by this constructor inherit all the methods of Ext.data.Record listed below.</p>
31  * @constructor
32  * <p>This constructor should not be used to create Record objects. Instead, use {@link #create} to
33  * generate a subclass of Ext.data.Record configured with information about its constituent fields.<p>
34  * <p><b>The generated constructor has the same signature as this constructor.</b></p>
35  * @param {Object} data (Optional) An object, the properties of which provide values for the new Record's
36  * fields. If not specified the <code>{@link Ext.data.Field#defaultValue defaultValue}</code>
37  * for each field will be assigned.
38  * @param {Object} id (Optional) The id of the Record. The id is used by the
39  * {@link Ext.data.Store} object which owns the Record to index its collection
40  * of Records (therefore this id should be unique within each store). If an
41  * <code>id</code> is not specified a <b><code>{@link #phantom}</code></b>
42  * Record will be created with an {@link #Record.id automatically generated id}.
43  */
44 Ext.data.Record = function(data, id){
45     // if no id, call the auto id method
46     this.id = (id || id === 0) ? id : Ext.data.Record.id(this);
47     this.data = data || {};
48 };
49
50 <div id="method-Ext.data.Record-create"></div>/**
51  * Generate a constructor for a specific Record layout.
52  * @param {Array} o An Array of <b>{@link Ext.data.Field Field}</b> definition objects.
53  * The constructor generated by this method may be used to create new Record instances. The data
54  * object must contain properties named after the {@link Ext.data.Field field}
55  * <b><tt>{@link Ext.data.Field#name}s</tt></b>.  Example usage:<pre><code>
56 // create a Record constructor from a description of the fields
57 var TopicRecord = Ext.data.Record.create([ // creates a subclass of Ext.data.Record
58     {{@link Ext.data.Field#name name}: 'title', {@link Ext.data.Field#mapping mapping}: 'topic_title'},
59     {name: 'author', mapping: 'username', allowBlank: false},
60     {name: 'totalPosts', mapping: 'topic_replies', type: 'int'},
61     {name: 'lastPost', mapping: 'post_time', type: 'date'},
62     {name: 'lastPoster', mapping: 'user2'},
63     {name: 'excerpt', mapping: 'post_text', allowBlank: false},
64     // In the simplest case, if no properties other than <tt>name</tt> are required,
65     // a field definition may consist of just a String for the field name.
66     'signature'
67 ]);
68
69 // create Record instance
70 var myNewRecord = new TopicRecord(
71     {
72         title: 'Do my job please',
73         author: 'noobie',
74         totalPosts: 1,
75         lastPost: new Date(),
76         lastPoster: 'Animal',
77         excerpt: 'No way dude!',
78         signature: ''
79     },
80     id // optionally specify the id of the record otherwise {@link #Record.id one is auto-assigned}
81 );
82 myStore.{@link Ext.data.Store#add add}(myNewRecord);
83 </code></pre>
84  * @method create
85  * @return {Function} A constructor which is used to create new Records according
86  * to the definition. The constructor has the same signature as {@link #Record}.
87  * @static
88  */
89 Ext.data.Record.create = function(o){
90     var f = Ext.extend(Ext.data.Record, {});
91     var p = f.prototype;
92     p.fields = new Ext.util.MixedCollection(false, function(field){
93         return field.name;
94     });
95     for(var i = 0, len = o.length; i < len; i++){
96         p.fields.add(new Ext.data.Field(o[i]));
97     }
98     f.getField = function(name){
99         return p.fields.get(name);
100     };
101     return f;
102 };
103
104 Ext.data.Record.PREFIX = 'ext-record';
105 Ext.data.Record.AUTO_ID = 1;
106 Ext.data.Record.EDIT = 'edit';
107 Ext.data.Record.REJECT = 'reject';
108 Ext.data.Record.COMMIT = 'commit';
109
110
111 <div id="method-Ext.data.Record-Record.id"></div>/**
112  * Generates a sequential id. This method is typically called when a record is {@link #create}d
113  * and {@link #Record no id has been specified}. The returned id takes the form:
114  * <tt>&#123;PREFIX}-&#123;AUTO_ID}</tt>.<div class="mdetail-params"><ul>
115  * <li><b><tt>PREFIX</tt></b> : String<p class="sub-desc"><tt>Ext.data.Record.PREFIX</tt>
116  * (defaults to <tt>'ext-record'</tt>)</p></li>
117  * <li><b><tt>AUTO_ID</tt></b> : String<p class="sub-desc"><tt>Ext.data.Record.AUTO_ID</tt>
118  * (defaults to <tt>1</tt> initially)</p></li>
119  * </ul></div>
120  * @param {Record} rec The record being created.  The record does not exist, it's a {@link #phantom}.
121  * @return {String} auto-generated string id, <tt>"ext-record-i++'</tt>;
122  */
123 Ext.data.Record.id = function(rec) {
124     rec.phantom = true;
125     return [Ext.data.Record.PREFIX, '-', Ext.data.Record.AUTO_ID++].join('');
126 };
127
128 Ext.data.Record.prototype = {
129     <div id="prop-Ext.data.Record-fields"></div>/**
130      * <p><b>This property is stored in the Record definition's <u>prototype</u></b></p>
131      * A MixedCollection containing the defined {@link Ext.data.Field Field}s for this Record.  Read-only.
132      * @property fields
133      * @type Ext.util.MixedCollection
134      */
135     <div id="prop-Ext.data.Record-data"></div>/**
136      * An object hash representing the data for this Record. Every field name in the Record definition
137      * is represented by a property of that name in this object. Note that unless you specified a field
138      * with {@link Ext.data.Field#name name} "id" in the Record definition, this will <b>not</b> contain
139      * an <tt>id</tt> property.
140      * @property data
141      * @type {Object}
142      */
143     <div id="prop-Ext.data.Record-id"></div>/**
144      * The unique ID of the Record {@link #Record as specified at construction time}.
145      * @property id
146      * @type {Object}
147      */
148     <div id="prop-Ext.data.Record-node"></div>/**
149      * <p><b>Only present if this Record was created by an {@link Ext.data.XmlReader XmlReader}</b>.</p>
150      * <p>The XML element which was the source of the data for this Record.</p>
151      * @property node
152      * @type {XMLElement}
153      */
154     <div id="prop-Ext.data.Record-json"></div>/**
155      * <p><b>Only present if this Record was created by an {@link Ext.data.ArrayReader ArrayReader} or a {@link Ext.data.JsonReader JsonReader}</b>.</p>
156      * <p>The Array or object which was the source of the data for this Record.</p>
157      * @property json
158      * @type {Array|Object}
159      */
160     <div id="prop-Ext.data.Record-dirty"></div>/**
161      * Readonly flag - true if this Record has been modified.
162      * @type Boolean
163      */
164     dirty : false,
165     editing : false,
166     error : null,
167     <div id="prop-Ext.data.Record-modified"></div>/**
168      * This object contains a key and value storing the original values of all modified
169      * fields or is null if no fields have been modified.
170      * @property modified
171      * @type {Object}
172      */
173     modified : null,
174     <div id="prop-Ext.data.Record-phantom"></div>/**
175      * <tt>true</tt> when the record does not yet exist in a server-side database (see
176      * {@link #markDirty}).  Any record which has a real database pk set as its id property
177      * is NOT a phantom -- it's real.
178      * @property phantom
179      * @type {Boolean}
180      */
181     phantom : false,
182
183     // private
184     join : function(store){
185         <div id="prop-Ext.data.Record-store"></div>/**
186          * The {@link Ext.data.Store} to which this Record belongs.
187          * @property store
188          * @type {Ext.data.Store}
189          */
190         this.store = store;
191     },
192
193     <div id="method-Ext.data.Record-set"></div>/**
194      * Set the {@link Ext.data.Field#name named field} to the specified value.  For example:
195      * <pre><code>
196 // record has a field named 'firstname'
197 var Employee = Ext.data.Record.{@link #create}([
198     {name: 'firstname'},
199     ...
200 ]);
201
202 // update the 2nd record in the store:
203 var rec = myStore.{@link Ext.data.Store#getAt getAt}(1);
204
205 // set the value (shows dirty flag):
206 rec.set('firstname', 'Betty');
207
208 // commit the change (removes dirty flag):
209 rec.{@link #commit}();
210
211 // update the record in the store, bypass setting dirty flag,
212 // and do not store the change in the {@link Ext.data.Store#getModifiedRecords modified records}
213 rec.{@link #data}['firstname'] = 'Wilma'; // updates record, but not the view
214 rec.{@link #commit}(); // updates the view
215      * </code></pre>
216      * <b>Notes</b>:<div class="mdetail-params"><ul>
217      * <li>If the store has a writer and <code>autoSave=true</code>, each set()
218      * will execute an XHR to the server.</li>
219      * <li>Use <code>{@link #beginEdit}</code> to prevent the store's <code>update</code>
220      * event firing while using set().</li>
221      * <li>Use <code>{@link #endEdit}</code> to have the store's <code>update</code>
222      * event fire.</li>
223      * </ul></div>
224      * @param {String} name The {@link Ext.data.Field#name name of the field} to set.
225      * @param {String/Object/Array} value The value to set the field to.
226      */
227     set : function(name, value){
228         var encode = Ext.isPrimitive(value) ? String : Ext.encode;
229         if(encode(this.data[name]) == encode(value)) {
230             return;
231         }        
232         this.dirty = true;
233         if(!this.modified){
234             this.modified = {};
235         }
236         if(this.modified[name] === undefined){
237             this.modified[name] = this.data[name];
238         }
239         this.data[name] = value;
240         if(!this.editing){
241             this.afterEdit();
242         }
243     },
244
245     // private
246     afterEdit : function(){
247         if (this.store != undefined && typeof this.store.afterEdit == "function") {
248             this.store.afterEdit(this);
249         }
250     },
251
252     // private
253     afterReject : function(){
254         if(this.store){
255             this.store.afterReject(this);
256         }
257     },
258
259     // private
260     afterCommit : function(){
261         if(this.store){
262             this.store.afterCommit(this);
263         }
264     },
265
266     <div id="method-Ext.data.Record-get"></div>/**
267      * Get the value of the {@link Ext.data.Field#name named field}.
268      * @param {String} name The {@link Ext.data.Field#name name of the field} to get the value of.
269      * @return {Object} The value of the field.
270      */
271     get : function(name){
272         return this.data[name];
273     },
274
275     <div id="method-Ext.data.Record-beginEdit"></div>/**
276      * Begin an edit. While in edit mode, no events (e.g.. the <code>update</code> event)
277      * are relayed to the containing store.
278      * See also: <code>{@link #endEdit}</code> and <code>{@link #cancelEdit}</code>.
279      */
280     beginEdit : function(){
281         this.editing = true;
282         this.modified = this.modified || {};
283     },
284
285     <div id="method-Ext.data.Record-cancelEdit"></div>/**
286      * Cancels all changes made in the current edit operation.
287      */
288     cancelEdit : function(){
289         this.editing = false;
290         delete this.modified;
291     },
292
293     <div id="method-Ext.data.Record-endEdit"></div>/**
294      * End an edit. If any data was modified, the containing store is notified
295      * (ie, the store's <code>update</code> event will fire).
296      */
297     endEdit : function(){
298         this.editing = false;
299         if(this.dirty){
300             this.afterEdit();
301         }
302     },
303
304     <div id="method-Ext.data.Record-reject"></div>/**
305      * Usually called by the {@link Ext.data.Store} which owns the Record.
306      * Rejects all changes made to the Record since either creation, or the last commit operation.
307      * Modified fields are reverted to their original values.
308      * <p>Developers should subscribe to the {@link Ext.data.Store#update} event
309      * to have their code notified of reject operations.</p>
310      * @param {Boolean} silent (optional) True to skip notification of the owning
311      * store of the change (defaults to false)
312      */
313     reject : function(silent){
314         var m = this.modified;
315         for(var n in m){
316             if(typeof m[n] != "function"){
317                 this.data[n] = m[n];
318             }
319         }
320         this.dirty = false;
321         delete this.modified;
322         this.editing = false;
323         if(silent !== true){
324             this.afterReject();
325         }
326     },
327
328     <div id="method-Ext.data.Record-commit"></div>/**
329      * Usually called by the {@link Ext.data.Store} which owns the Record.
330      * Commits all changes made to the Record since either creation, or the last commit operation.
331      * <p>Developers should subscribe to the {@link Ext.data.Store#update} event
332      * to have their code notified of commit operations.</p>
333      * @param {Boolean} silent (optional) True to skip notification of the owning
334      * store of the change (defaults to false)
335      */
336     commit : function(silent){
337         this.dirty = false;
338         delete this.modified;
339         this.editing = false;
340         if(silent !== true){
341             this.afterCommit();
342         }
343     },
344
345     <div id="method-Ext.data.Record-getChanges"></div>/**
346      * Gets a hash of only the fields that have been modified since this Record was created or commited.
347      * @return Object
348      */
349     getChanges : function(){
350         var m = this.modified, cs = {};
351         for(var n in m){
352             if(m.hasOwnProperty(n)){
353                 cs[n] = this.data[n];
354             }
355         }
356         return cs;
357     },
358
359     // private
360     hasError : function(){
361         return this.error !== null;
362     },
363
364     // private
365     clearError : function(){
366         this.error = null;
367     },
368
369     <div id="method-Ext.data.Record-copy"></div>/**
370      * Creates a copy (clone) of this Record.
371      * @param {String} id (optional) A new Record id, defaults to the id
372      * of the record being copied. See <code>{@link #id}</code>. 
373      * To generate a phantom record with a new id use:<pre><code>
374 var rec = record.copy(); // clone the record
375 Ext.data.Record.id(rec); // automatically generate a unique sequential id
376      * </code></pre>
377      * @return {Record}
378      */
379     copy : function(newId) {
380         return new this.constructor(Ext.apply({}, this.data), newId || this.id);
381     },
382
383     <div id="method-Ext.data.Record-isModified"></div>/**
384      * Returns <tt>true</tt> if the passed field name has been <code>{@link #modified}</code>
385      * since the load or last commit.
386      * @param {String} fieldName {@link Ext.data.Field.{@link Ext.data.Field#name}
387      * @return {Boolean}
388      */
389     isModified : function(fieldName){
390         return !!(this.modified && this.modified.hasOwnProperty(fieldName));
391     },
392
393     <div id="method-Ext.data.Record-isValid"></div>/**
394      * By default returns <tt>false</tt> if any {@link Ext.data.Field field} within the
395      * record configured with <tt>{@link Ext.data.Field#allowBlank} = false</tt> returns
396      * <tt>true</tt> from an {@link Ext}.{@link Ext#isEmpty isempty} test.
397      * @return {Boolean}
398      */
399     isValid : function() {
400         return this.fields.find(function(f) {
401             return (f.allowBlank === false && Ext.isEmpty(this.data[f.name])) ? true : false;
402         },this) ? false : true;
403     },
404
405     <div id="method-Ext.data.Record-markDirty"></div>/**
406      * <p>Marks this <b>Record</b> as <code>{@link #dirty}</code>.  This method
407      * is used interally when adding <code>{@link #phantom}</code> records to a
408      * {@link Ext.data.Store#writer writer enabled store}.</p>
409      * <br><p>Marking a record <code>{@link #dirty}</code> causes the phantom to
410      * be returned by {@link Ext.data.Store#getModifiedRecords} where it will
411      * have a create action composed for it during {@link Ext.data.Store#save store save}
412      * operations.</p>
413      */
414     markDirty : function(){
415         this.dirty = true;
416         if(!this.modified){
417             this.modified = {};
418         }
419         this.fields.each(function(f) {
420             this.modified[f.name] = this.data[f.name];
421         },this);
422     }
423 };
424 </pre>    
425 </body>
426 </html>