docs/source/Record.html

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