source: trunk/web/addons/job_monarch/lib/extjs-30/src/data/Record.js @ 625

Last change on this file since 625 was 625, checked in by ramonb, 15 years ago

lib/extjs-30:

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