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