← Back to branch summary

~cdparra/gelee/trunk

« back to all changes in this revision

Viewing changes to webui/ecosystem/workspace/extjs/docs/source/Record.html

  • Committer: parra
  • Date: 2010-03-15 15:56:56 UTC
  • Revision ID: svn-v4:ac5bba68-f036-4e09-846e-8f32731cc928:trunk/gelee:1448
merged gelee at svn

Show diffs side-by-side

added added

removed removed

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