3 * Copyright(c) 2006-2009 Ext JS, LLC
5 * http://www.extjs.com/license
8 * @class Ext.data.Record
9 * <p>Instances of this class encapsulate both Record <em>definition</em> information, and Record
10 * <em>value</em> information for use in {@link Ext.data.Store} objects, or any code which needs
11 * to access Records cached in an {@link Ext.data.Store} object.</p>
12 * <p>Constructors for this class are generated by passing an Array of field definition objects to {@link #create}.
13 * Instances are usually only created by {@link Ext.data.Reader} implementations when processing unformatted data
15 * <p>Note that an instance of a Record class may only belong to one {@link Ext.data.Store Store} at a time.
16 * In order to copy data from one Store to another, use the {@link #copy} method to create an exact
17 * copy of the Record, and insert the new instance into the other Store.</p>
18 * <p>When serializing a Record for submission to the server, be aware that it contains many private
19 * properties, and also a reference to its owning Store which in turn holds references to its Records.
20 * This means that a whole Record may not be encoded using {@link Ext.util.JSON.encode}. Instead, use the
21 * <code>{@link #data}</code> and <code>{@link #id}</code> properties.</p>
22 * <p>Record objects generated by this constructor inherit all the methods of Ext.data.Record listed below.</p>
24 * <p>This constructor should not be used to create Record objects. Instead, use {@link #create} to
25 * generate a subclass of Ext.data.Record configured with information about its constituent fields.<p>
26 * <p><b>The generated constructor has the same signature as this constructor.</b></p>
27 * @param {Object} data (Optional) An object, the properties of which provide values for the new Record's
28 * fields. If not specified the <code>{@link Ext.data.Field#defaultValue defaultValue}</code>
29 * for each field will be assigned.
30 * @param {Object} id (Optional) The id of the Record. The id is used by the
31 * {@link Ext.data.Store} object which owns the Record to index its collection
32 * of Records (therefore this id should be unique within each store). If an
33 * <code>id</code> is not specified a <b><code>{@link #phantom}</code></b>
34 * Record will be created with an {@link #Record.id automatically generated id}.
36 Ext.data.Record = function(data, id){
37 // if no id, call the auto id method
38 this.id = (id || id === 0) ? id : Ext.data.Record.id(this);
39 this.data = data || {};
43 * Generate a constructor for a specific Record layout.
44 * @param {Array} o An Array of <b>{@link Ext.data.Field Field}</b> definition objects.
45 * The constructor generated by this method may be used to create new Record instances. The data
46 * object must contain properties named after the {@link Ext.data.Field field}
47 * <b><tt>{@link Ext.data.Field#name}s</tt></b>. Example usage:<pre><code>
48 // create a Record constructor from a description of the fields
49 var TopicRecord = Ext.data.Record.create([ // creates a subclass of Ext.data.Record
50 {{@link Ext.data.Field#name name}: 'title', {@link Ext.data.Field#mapping mapping}: 'topic_title'},
51 {name: 'author', mapping: 'username', allowBlank: false},
52 {name: 'totalPosts', mapping: 'topic_replies', type: 'int'},
53 {name: 'lastPost', mapping: 'post_time', type: 'date'},
54 {name: 'lastPoster', mapping: 'user2'},
55 {name: 'excerpt', mapping: 'post_text', allowBlank: false},
56 // In the simplest case, if no properties other than <tt>name</tt> are required,
57 // a field definition may consist of just a String for the field name.
61 // create Record instance
62 var myNewRecord = new TopicRecord(
64 title: 'Do my job please',
69 excerpt: 'No way dude!',
72 id // optionally specify the id of the record otherwise {@link #Record.id one is auto-assigned}
74 myStore.{@link Ext.data.Store#add add}(myNewRecord);
77 * @return {function} A constructor which is used to create new Records according
78 * to the definition. The constructor has the same signature as {@link #Record}.
81 Ext.data.Record.create = function(o){
82 var f = Ext.extend(Ext.data.Record, {});
84 p.fields = new Ext.util.MixedCollection(false, function(field){
87 for(var i = 0, len = o.length; i < len; i++){
88 p.fields.add(new Ext.data.Field(o[i]));
90 f.getField = function(name){
91 return p.fields.get(name);
96 Ext.data.Record.PREFIX = 'ext-record';
97 Ext.data.Record.AUTO_ID = 1;
98 Ext.data.Record.EDIT = 'edit';
99 Ext.data.Record.REJECT = 'reject';
100 Ext.data.Record.COMMIT = 'commit';
104 * Generates a sequential id. This method is typically called when a record is {@link #create}d
105 * and {@link #Record no id has been specified}. The returned id takes the form:
106 * <tt>{PREFIX}-{AUTO_ID}</tt>.<div class="mdetail-params"><ul>
107 * <li><b><tt>PREFIX</tt></b> : String<p class="sub-desc"><tt>Ext.data.Record.PREFIX</tt>
108 * (defaults to <tt>'ext-record'</tt>)</p></li>
109 * <li><b><tt>AUTO_ID</tt></b> : String<p class="sub-desc"><tt>Ext.data.Record.AUTO_ID</tt>
110 * (defaults to <tt>1</tt> initially)</p></li>
112 * @param {Record} rec The record being created. The record does not exist, it's a {@link #phantom}.
113 * @return {String} auto-generated string id, <tt>"ext-record-i++'</tt>;
115 Ext.data.Record.id = function(rec) {
117 return [Ext.data.Record.PREFIX, '-', Ext.data.Record.AUTO_ID++].join('');
120 Ext.data.Record.prototype = {
122 * <p><b>This property is stored in the Record definition's <u>prototype</u></b></p>
123 * A MixedCollection containing the defined {@link Ext.data.Field Field}s for this Record. Read-only.
125 * @type Ext.util.MixedCollection
128 * An object hash representing the data for this Record. Every field name in the Record definition
129 * is represented by a property of that name in this object. Note that unless you specified a field
130 * with {@link Ext.data.Field#name name} "id" in the Record definition, this will <b>not</b> contain
131 * an <tt>id</tt> property.
136 * The unique ID of the Record {@link #Record as specified at construction time}.
141 * <p><b>Only present if this Record was created by an {@link Ext.data.XmlReader XmlReader}</b>.</p>
142 * <p>The XML element which was the source of the data for this Record.</p>
147 * <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>
148 * <p>The Array or object which was the source of the data for this Record.</p>
150 * @type {Array|Object}
153 * Readonly flag - true if this Record has been modified.
160 * This object contains a key and value storing the original values of all modified
161 * fields or is null if no fields have been modified.
167 * <tt>true</tt> when the record does not yet exist in a server-side database (see
168 * {@link #markDirty}). Any record which has a real database pk set as its id property
169 * is NOT a phantom -- it's real.
176 join : function(store){
178 * The {@link Ext.data.Store} to which this Record belongs.
180 * @type {Ext.data.Store}
186 * Set the {@link Ext.data.Field#name named field} to the specified value. For example:
188 // record has a field named 'firstname'
189 var Employee = Ext.data.Record.{@link #create}([
194 // update the 2nd record in the store:
195 var rec = myStore.{@link Ext.data.Store#getAt getAt}(1);
197 // set the value (shows dirty flag):
198 rec.set('firstname', 'Betty');
200 // commit the change (removes dirty flag):
201 rec.{@link #commit}();
203 // update the record in the store, bypass setting dirty flag,
204 // and do not store the change in the {@link Ext.data.Store#getModifiedRecords modified records}
205 rec.{@link #data}['firstname'] = 'Wilma'; // updates record, but not the view
206 rec.{@link #commit}(); // updates the view
208 * <b>Notes</b>:<div class="mdetail-params"><ul>
209 * <li>If the store has a writer and <code>autoSave=true</code>, each set()
210 * will execute an XHR to the server.</li>
211 * <li>Use <code>{@link #beginEdit}</code> to prevent the store's <code>update</code>
212 * event firing while using set().</li>
213 * <li>Use <code>{@link #endEdit}</code> to have the store's <code>update</code>
216 * @param {String} name The {@link Ext.data.Field#name name of the field} to set.
217 * @param {String/Object/Array} value The value to set the field to.
219 set : function(name, value){
220 var encode = Ext.isPrimitive(value) ? String : Ext.encode;
221 if(encode(this.data[name]) == encode(value)) {
228 if(this.modified[name] === undefined){
229 this.modified[name] = this.data[name];
231 this.data[name] = value;
238 afterEdit : function(){
240 this.store.afterEdit(this);
245 afterReject : function(){
247 this.store.afterReject(this);
252 afterCommit : function(){
254 this.store.afterCommit(this);
259 * Get the value of the {@link Ext.data.Field#name named field}.
260 * @param {String} name The {@link Ext.data.Field#name name of the field} to get the value of.
261 * @return {Object} The value of the field.
263 get : function(name){
264 return this.data[name];
268 * Begin an edit. While in edit mode, no events (e.g.. the <code>update</code> event)
269 * are relayed to the containing store.
270 * See also: <code>{@link #endEdit}</code> and <code>{@link #cancelEdit}</code>.
272 beginEdit : function(){
274 this.modified = this.modified || {};
278 * Cancels all changes made in the current edit operation.
280 cancelEdit : function(){
281 this.editing = false;
282 delete this.modified;
286 * End an edit. If any data was modified, the containing store is notified
287 * (ie, the store's <code>update</code> event will fire).
289 endEdit : function(){
290 this.editing = false;
297 * Usually called by the {@link Ext.data.Store} which owns the Record.
298 * Rejects all changes made to the Record since either creation, or the last commit operation.
299 * Modified fields are reverted to their original values.
300 * <p>Developers should subscribe to the {@link Ext.data.Store#update} event
301 * to have their code notified of reject operations.</p>
302 * @param {Boolean} silent (optional) True to skip notification of the owning
303 * store of the change (defaults to false)
305 reject : function(silent){
306 var m = this.modified;
308 if(typeof m[n] != "function"){
313 delete this.modified;
314 this.editing = false;
321 * Usually called by the {@link Ext.data.Store} which owns the Record.
322 * Commits all changes made to the Record since either creation, or the last commit operation.
323 * <p>Developers should subscribe to the {@link Ext.data.Store#update} event
324 * to have their code notified of commit operations.</p>
325 * @param {Boolean} silent (optional) True to skip notification of the owning
326 * store of the change (defaults to false)
328 commit : function(silent){
330 delete this.modified;
331 this.editing = false;
338 * Gets a hash of only the fields that have been modified since this Record was created or commited.
341 getChanges : function(){
342 var m = this.modified, cs = {};
344 if(m.hasOwnProperty(n)){
345 cs[n] = this.data[n];
352 hasError : function(){
353 return this.error !== null;
357 clearError : function(){
362 * Creates a copy (clone) of this Record.
363 * @param {String} id (optional) A new Record id, defaults to the id
364 * of the record being copied. See <code>{@link #id}</code>.
365 * To generate a phantom record with a new id use:<pre><code>
366 var rec = record.copy(); // clone the record
367 Ext.data.Record.id(rec); // automatically generate a unique sequential id
371 copy : function(newId) {
372 return new this.constructor(Ext.apply({}, this.data), newId || this.id);
376 * Returns <tt>true</tt> if the passed field name has been <code>{@link #modified}</code>
377 * since the load or last commit.
378 * @param {String} fieldName {@link Ext.data.Field.{@link Ext.data.Field#name}
381 isModified : function(fieldName){
382 return !!(this.modified && this.modified.hasOwnProperty(fieldName));
386 * By default returns <tt>false</tt> if any {@link Ext.data.Field field} within the
387 * record configured with <tt>{@link Ext.data.Field#allowBlank} = false</tt> returns
388 * <tt>true</tt> from an {@link Ext}.{@link Ext#isEmpty isempty} test.
391 isValid : function() {
392 return this.fields.find(function(f) {
393 return (f.allowBlank === false && Ext.isEmpty(this.data[f.name])) ? true : false;
394 },this) ? false : true;
398 * <p>Marks this <b>Record</b> as <code>{@link #dirty}</code>. This method
399 * is used interally when adding <code>{@link #phantom}</code> records to a
400 * {@link Ext.data.Store#writer writer enabled store}.</p>
401 * <br><p>Marking a record <code>{@link #dirty}</code> causes the phantom to
402 * be returned by {@link Ext.data.Store#getModifiedRecords} where it will
403 * have a create action composed for it during {@link Ext.data.Store#save store save}
406 markDirty : function(){
411 this.fields.each(function(f) {
412 this.modified[f.name] = this.data[f.name];