[76] | 1 | /*! |
---|
| 2 | * Ext JS Library 3.4.0 |
---|
| 3 | * Copyright(c) 2006-2011 Sencha Inc. |
---|
| 4 | * licensing@sencha.com |
---|
| 5 | * http://www.sencha.com/license |
---|
| 6 | */ |
---|
| 7 | /** |
---|
| 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 |
---|
| 14 | * objects.</p> |
---|
| 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> |
---|
| 23 | * @constructor |
---|
| 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}. |
---|
| 35 | */ |
---|
| 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 || {}; |
---|
| 40 | }; |
---|
| 41 | |
---|
| 42 | /** |
---|
| 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. |
---|
| 58 | 'signature' |
---|
| 59 | ]); |
---|
| 60 | |
---|
| 61 | // create Record instance |
---|
| 62 | var myNewRecord = new TopicRecord( |
---|
| 63 | { |
---|
| 64 | title: 'Do my job please', |
---|
| 65 | author: 'noobie', |
---|
| 66 | totalPosts: 1, |
---|
| 67 | lastPost: new Date(), |
---|
| 68 | lastPoster: 'Animal', |
---|
| 69 | excerpt: 'No way dude!', |
---|
| 70 | signature: '' |
---|
| 71 | }, |
---|
| 72 | id // optionally specify the id of the record otherwise {@link #Record.id one is auto-assigned} |
---|
| 73 | ); |
---|
| 74 | myStore.{@link Ext.data.Store#add add}(myNewRecord); |
---|
| 75 | </code></pre> |
---|
| 76 | * @method create |
---|
| 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}. |
---|
| 79 | * @static |
---|
| 80 | */ |
---|
| 81 | Ext.data.Record.create = function(o){ |
---|
| 82 | var f = Ext.extend(Ext.data.Record, {}); |
---|
| 83 | var p = f.prototype; |
---|
| 84 | p.fields = new Ext.util.MixedCollection(false, function(field){ |
---|
| 85 | return field.name; |
---|
| 86 | }); |
---|
| 87 | for(var i = 0, len = o.length; i < len; i++){ |
---|
| 88 | p.fields.add(new Ext.data.Field(o[i])); |
---|
| 89 | } |
---|
| 90 | f.getField = function(name){ |
---|
| 91 | return p.fields.get(name); |
---|
| 92 | }; |
---|
| 93 | return f; |
---|
| 94 | }; |
---|
| 95 | |
---|
| 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'; |
---|
| 101 | |
---|
| 102 | |
---|
| 103 | /** |
---|
| 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> |
---|
| 111 | * </ul></div> |
---|
| 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>; |
---|
| 114 | */ |
---|
| 115 | Ext.data.Record.id = function(rec) { |
---|
| 116 | rec.phantom = true; |
---|
| 117 | return [Ext.data.Record.PREFIX, '-', Ext.data.Record.AUTO_ID++].join(''); |
---|
| 118 | }; |
---|
| 119 | |
---|
| 120 | Ext.data.Record.prototype = { |
---|
| 121 | /** |
---|
| 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. |
---|
| 124 | * @property fields |
---|
| 125 | * @type Ext.util.MixedCollection |
---|
| 126 | */ |
---|
| 127 | /** |
---|
| 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. |
---|
| 132 | * @property data |
---|
| 133 | * @type {Object} |
---|
| 134 | */ |
---|
| 135 | /** |
---|
| 136 | * The unique ID of the Record {@link #Record as specified at construction time}. |
---|
| 137 | * @property id |
---|
| 138 | * @type {Object} |
---|
| 139 | */ |
---|
| 140 | /** |
---|
| 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> |
---|
| 143 | * @property node |
---|
| 144 | * @type {XMLElement} |
---|
| 145 | */ |
---|
| 146 | /** |
---|
| 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> |
---|
| 149 | * @property json |
---|
| 150 | * @type {Array|Object} |
---|
| 151 | */ |
---|
| 152 | /** |
---|
| 153 | * Readonly flag - true if this Record has been modified. |
---|
| 154 | * @type Boolean |
---|
| 155 | */ |
---|
| 156 | dirty : false, |
---|
| 157 | editing : false, |
---|
| 158 | error : null, |
---|
| 159 | /** |
---|
| 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. |
---|
| 162 | * @property modified |
---|
| 163 | * @type {Object} |
---|
| 164 | */ |
---|
| 165 | modified : null, |
---|
| 166 | /** |
---|
| 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. |
---|
| 170 | * @property phantom |
---|
| 171 | * @type {Boolean} |
---|
| 172 | */ |
---|
| 173 | phantom : false, |
---|
| 174 | |
---|
| 175 | // private |
---|
| 176 | join : function(store){ |
---|
| 177 | /** |
---|
| 178 | * The {@link Ext.data.Store} to which this Record belongs. |
---|
| 179 | * @property store |
---|
| 180 | * @type {Ext.data.Store} |
---|
| 181 | */ |
---|
| 182 | this.store = store; |
---|
| 183 | }, |
---|
| 184 | |
---|
| 185 | /** |
---|
| 186 | * Set the {@link Ext.data.Field#name named field} to the specified value. For example: |
---|
| 187 | * <pre><code> |
---|
| 188 | // record has a field named 'firstname' |
---|
| 189 | var Employee = Ext.data.Record.{@link #create}([ |
---|
| 190 | {name: 'firstname'}, |
---|
| 191 | ... |
---|
| 192 | ]); |
---|
| 193 | |
---|
| 194 | // update the 2nd record in the store: |
---|
| 195 | var rec = myStore.{@link Ext.data.Store#getAt getAt}(1); |
---|
| 196 | |
---|
| 197 | // set the value (shows dirty flag): |
---|
| 198 | rec.set('firstname', 'Betty'); |
---|
| 199 | |
---|
| 200 | // commit the change (removes dirty flag): |
---|
| 201 | rec.{@link #commit}(); |
---|
| 202 | |
---|
| 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 |
---|
| 207 | * </code></pre> |
---|
| 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> |
---|
| 214 | * event fire.</li> |
---|
| 215 | * </ul></div> |
---|
| 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. |
---|
| 218 | */ |
---|
| 219 | set : function(name, value){ |
---|
| 220 | var encode = Ext.isPrimitive(value) ? String : Ext.encode; |
---|
| 221 | if(encode(this.data[name]) == encode(value)) { |
---|
| 222 | return; |
---|
| 223 | } |
---|
| 224 | this.dirty = true; |
---|
| 225 | if(!this.modified){ |
---|
| 226 | this.modified = {}; |
---|
| 227 | } |
---|
| 228 | if(this.modified[name] === undefined){ |
---|
| 229 | this.modified[name] = this.data[name]; |
---|
| 230 | } |
---|
| 231 | this.data[name] = value; |
---|
| 232 | if(!this.editing){ |
---|
| 233 | this.afterEdit(); |
---|
| 234 | } |
---|
| 235 | }, |
---|
| 236 | |
---|
| 237 | // private |
---|
| 238 | afterEdit : function(){ |
---|
| 239 | if (this.store != undefined && typeof this.store.afterEdit == "function") { |
---|
| 240 | this.store.afterEdit(this); |
---|
| 241 | } |
---|
| 242 | }, |
---|
| 243 | |
---|
| 244 | // private |
---|
| 245 | afterReject : function(){ |
---|
| 246 | if(this.store){ |
---|
| 247 | this.store.afterReject(this); |
---|
| 248 | } |
---|
| 249 | }, |
---|
| 250 | |
---|
| 251 | // private |
---|
| 252 | afterCommit : function(){ |
---|
| 253 | if(this.store){ |
---|
| 254 | this.store.afterCommit(this); |
---|
| 255 | } |
---|
| 256 | }, |
---|
| 257 | |
---|
| 258 | /** |
---|
| 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. |
---|
| 262 | */ |
---|
| 263 | get : function(name){ |
---|
| 264 | return this.data[name]; |
---|
| 265 | }, |
---|
| 266 | |
---|
| 267 | /** |
---|
| 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>. |
---|
| 271 | */ |
---|
| 272 | beginEdit : function(){ |
---|
| 273 | this.editing = true; |
---|
| 274 | this.modified = this.modified || {}; |
---|
| 275 | }, |
---|
| 276 | |
---|
| 277 | /** |
---|
| 278 | * Cancels all changes made in the current edit operation. |
---|
| 279 | */ |
---|
| 280 | cancelEdit : function(){ |
---|
| 281 | this.editing = false; |
---|
| 282 | delete this.modified; |
---|
| 283 | }, |
---|
| 284 | |
---|
| 285 | /** |
---|
| 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). |
---|
| 288 | */ |
---|
| 289 | endEdit : function(){ |
---|
| 290 | this.editing = false; |
---|
| 291 | if(this.dirty){ |
---|
| 292 | this.afterEdit(); |
---|
| 293 | } |
---|
| 294 | }, |
---|
| 295 | |
---|
| 296 | /** |
---|
| 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) |
---|
| 304 | */ |
---|
| 305 | reject : function(silent){ |
---|
| 306 | var m = this.modified; |
---|
| 307 | for(var n in m){ |
---|
| 308 | if(typeof m[n] != "function"){ |
---|
| 309 | this.data[n] = m[n]; |
---|
| 310 | } |
---|
| 311 | } |
---|
| 312 | this.dirty = false; |
---|
| 313 | delete this.modified; |
---|
| 314 | this.editing = false; |
---|
| 315 | if(silent !== true){ |
---|
| 316 | this.afterReject(); |
---|
| 317 | } |
---|
| 318 | }, |
---|
| 319 | |
---|
| 320 | /** |
---|
| 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) |
---|
| 327 | */ |
---|
| 328 | commit : function(silent){ |
---|
| 329 | this.dirty = false; |
---|
| 330 | delete this.modified; |
---|
| 331 | this.editing = false; |
---|
| 332 | if(silent !== true){ |
---|
| 333 | this.afterCommit(); |
---|
| 334 | } |
---|
| 335 | }, |
---|
| 336 | |
---|
| 337 | /** |
---|
| 338 | * Gets a hash of only the fields that have been modified since this Record was created or commited. |
---|
| 339 | * @return Object |
---|
| 340 | */ |
---|
| 341 | getChanges : function(){ |
---|
| 342 | var m = this.modified, cs = {}; |
---|
| 343 | for(var n in m){ |
---|
| 344 | if(m.hasOwnProperty(n)){ |
---|
| 345 | cs[n] = this.data[n]; |
---|
| 346 | } |
---|
| 347 | } |
---|
| 348 | return cs; |
---|
| 349 | }, |
---|
| 350 | |
---|
| 351 | // private |
---|
| 352 | hasError : function(){ |
---|
| 353 | return this.error !== null; |
---|
| 354 | }, |
---|
| 355 | |
---|
| 356 | // private |
---|
| 357 | clearError : function(){ |
---|
| 358 | this.error = null; |
---|
| 359 | }, |
---|
| 360 | |
---|
| 361 | /** |
---|
| 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 |
---|
| 368 | * </code></pre> |
---|
| 369 | * @return {Record} |
---|
| 370 | */ |
---|
| 371 | copy : function(newId) { |
---|
| 372 | return new this.constructor(Ext.apply({}, this.data), newId || this.id); |
---|
| 373 | }, |
---|
| 374 | |
---|
| 375 | /** |
---|
| 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} |
---|
| 379 | * @return {Boolean} |
---|
| 380 | */ |
---|
| 381 | isModified : function(fieldName){ |
---|
| 382 | return !!(this.modified && this.modified.hasOwnProperty(fieldName)); |
---|
| 383 | }, |
---|
| 384 | |
---|
| 385 | /** |
---|
| 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. |
---|
| 389 | * @return {Boolean} |
---|
| 390 | */ |
---|
| 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; |
---|
| 395 | }, |
---|
| 396 | |
---|
| 397 | /** |
---|
| 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} |
---|
| 404 | * operations.</p> |
---|
| 405 | */ |
---|
| 406 | markDirty : function(){ |
---|
| 407 | this.dirty = true; |
---|
| 408 | if(!this.modified){ |
---|
| 409 | this.modified = {}; |
---|
| 410 | } |
---|
| 411 | this.fields.each(function(f) { |
---|
| 412 | this.modified[f.name] = this.data[f.name]; |
---|
| 413 | },this); |
---|
| 414 | } |
---|
| 415 | }; |
---|