commit extjs-2.2.1
[extjs.git] / docs / output / Ext.data.Record.html
1         <div class="body-wrap">
2         <div class="top-tools">
3             <a class="inner-link" href="#Ext.data.Record-props"><img src="../resources/images/default/s.gif" class="item-icon icon-prop">Properties</a>
4             <a class="inner-link" href="#Ext.data.Record-methods"><img src="../resources/images/default/s.gif" class="item-icon icon-method">Methods</a>
5             <a class="inner-link" href="#Ext.data.Record-events"><img src="../resources/images/default/s.gif" class="item-icon icon-event">Events</a>
6                         <a class="bookmark" href="../docs/?class=Ext.data.Record"><img src="../resources/images/default/s.gif" class="item-icon icon-fav">Direct Link</a>
7         </div>
8                 <h1>Class Ext.data.Record</h1>
9         <table cellspacing="0">
10             <tr><td class="label">Package:</td><td class="hd-info">Ext.data</td></tr>
11             <tr><td class="label">Defined In:</td><td class="hd-info"><a href="../src/Record.js" target="_blank">Record.js</a></td></tr>
12             <tr><td class="label">Class:</td><td class="hd-info">Record</td></tr>
13                                     <tr><td class="label">Extends:</td><td class="hd-info">Object</td></tr>
14                     </table>
15         <div class="description">
16             *
17 <p>Instances of this class encapsulate both Record <em>definition</em> information, and Record
18 <em>value</em> information for use in <a ext:cls="Ext.data.Store" href="output/Ext.data.Store.html">Ext.data.Store</a> objects, or any code which needs
19 to access Records cached in an <a ext:cls="Ext.data.Store" href="output/Ext.data.Store.html">Ext.data.Store</a> object.</p>
20 <p>Constructors for this class are generated by passing an Array of field definition objects to <a ext:cls="Ext.data.Record" ext:member="create" href="output/Ext.data.Record.html#create">create</a>.
21 Instances are usually only created by <a ext:cls="Ext.data.Reader" href="output/Ext.data.Reader.html">Ext.data.Reader</a> implementations when processing unformatted data
22 objects.</p>
23 <p>Note that an instance of a Record class may only belong to one <a ext:cls="Ext.data.Store" href="output/Ext.data.Store.html">Store</a> at a time.
24 In order to copy data from one Store to another, use the <a ext:cls="Ext.data.Record" ext:member="copy" href="output/Ext.data.Record.html#copy">copy</a> method to create an exact
25 copy of the Record, and insert the new instance into the other Store.</p>
26 <p>When serializing a Record for submission to the server, be aware that it contains many private
27 properties, and also a reference to its owning Store which in turn holds references to its Records.
28 This means that a Record may not be encoded using <a ext:cls="Ext.util.JSON.encode" href="output/Ext.util.JSON.encode.html">Ext.util.JSON.encode</a>. Instead, use the
29 <a ext:cls="data" href="output/data.html">data</a> and <a ext:cls="id" href="output/id.html">id</a> properties.</p>
30 Record objects generated by this constructor inherit all the methods of Ext.data.Record listed below.        </div>
31         
32         <div class="hr"></div>
33                 <a id="Ext.data.Record-props"></a>
34         <h2>Public Properties</h2>
35                 <table cellspacing="0" class="member-table">
36             <tr>
37                 <th class="sig-header" colspan="2">Property</th>
38                 <th class="msource-header">Defined By</th>
39             </tr>
40                 <tr class="property-row expandable">\r
41         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
42         <td class="sig">\r
43         <a id="Ext.data.Record-data"></a>\r
44             <b>data</b> : Object            <div class="mdesc">\r
45                         <div class="short">
46 An object hash representing the data for this Record. Every field name in the Record definition
47 is represented by a ...</div>\r
48             <div class="long">\r
49                 
50 An object hash representing the data for this Record. Every field name in the Record definition
51 is represented by a property of that name in this object. Note that unless you specified a field
52 with name "id" in the Record definition, this will <b>not</b> contain an <tt>id</tt> property.            </div>\r
53                         </div>\r
54         </td>\r
55         <td class="msource">Record</td>\r
56     </tr>\r
57         <tr class="property-row alt">\r
58         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
59         <td class="sig">\r
60         <a id="Ext.data.Record-dirty"></a>\r
61             <b>dirty</b> : Boolean            <div class="mdesc">\r
62                             
63 Readonly flag - true if this Record has been modified.                        </div>\r
64         </td>\r
65         <td class="msource">Record</td>\r
66     </tr>\r
67         <tr class="property-row expandable">\r
68         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
69         <td class="sig">\r
70         <a id="Ext.data.Record-fields"></a>\r
71             <b>fields</b> : Ext.util.MixedCollection            <div class="mdesc">\r
72                         <div class="short">This property is stored in the Record definition's prototype
73 A MixedCollection containing the defined Fields for this...</div>\r
74             <div class="long">\r
75                 <p><b>This property is stored in the Record definition's <u>prototype</u></b></p>
76 A MixedCollection containing the defined <a ext:cls="Ext.data.Field" href="output/Ext.data.Field.html">Field</a>s for this Record.  Read-only.            </div>\r
77                         </div>\r
78         </td>\r
79         <td class="msource">Record</td>\r
80     </tr>\r
81         <tr class="property-row alt">\r
82         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
83         <td class="sig">\r
84         <a id="Ext.data.Record-id"></a>\r
85             <b>id</b> : Object            <div class="mdesc">\r
86                             
87 The unique ID of the Record as specified at construction time.                        </div>\r
88         </td>\r
89         <td class="msource">Record</td>\r
90     </tr>\r
91         <tr class="property-row expandable">\r
92         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
93         <td class="sig">\r
94         <a id="Ext.data.Record-modified"></a>\r
95             <b>modified</b> : Object            <div class="mdesc">\r
96                         <div class="short">This object contains a key and value storing the original values of all modified fields or is null if no fields have ...</div>\r
97             <div class="long">\r
98                 This object contains a key and value storing the original values of all modified fields or is null if no fields have been modified.            </div>\r
99                         </div>\r
100         </td>\r
101         <td class="msource">Record</td>\r
102     </tr>\r
103             </table>
104                 <a id="Ext.data.Record-methods"></a>
105         <h2>Public Methods</h2>
106                 <table cellspacing="0" class="member-table">
107             <tr>
108                 <th class="sig-header" colspan="2">Method</th>
109                 <th class="msource-header">Defined By</th>
110             </tr>
111                 <tr class="method-row expandable">\r
112         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
113         <td class="sig">\r
114         <a id="Ext.data.Record-Record"></a>\r
115             <b>Record</b>(&nbsp;<code>Array data</code>, <span class="optional" title="Optional">[<code>Object id</code>]</span>&nbsp;)            <div class="mdesc">\r
116                         <div class="short">This constructor should not be used to create Record objects. Instead, use the constructor generated by
117 create. The p...</div>\r
118             <div class="long">\r
119                 This constructor should not be used to create Record objects. Instead, use the constructor generated by
120 <a ext:cls="Ext.data.Record" ext:member="create" href="output/Ext.data.Record.html#create">create</a>. The parameters are the same.    <div class="mdetail-params">\r
121         <strong>Parameters:</strong>\r
122         <ul><li><code>data</code> : Array<div class="sub-desc">An object, the properties of which provide values for the new Record's fields.</div></li><li><code>id</code> : Object<div class="sub-desc">(Optional) The id of the Record. This id should be unique, and is used by the
123 <a ext:cls="Ext.data.Store" href="output/Ext.data.Store.html">Ext.data.Store</a> object which owns the Record to index its collection of Records. If
124 not specified an integer id is generated.</div></li>        </ul>\r
125         <strong>Returns:</strong>\r
126         <ul>\r
127             <li><code></code></li>\r
128         </ul>\r
129     </div>\r
130                 </div>\r
131                         </div>\r
132         </td>\r
133         <td class="msource">Record</td>\r
134     </tr>\r
135         <tr class="method-row alt expandable">\r
136         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
137         <td class="sig">\r
138         <a id="Ext.data.Record-beginEdit"></a>\r
139             <b>beginEdit</b>() : void            <div class="mdesc">\r
140                         <div class="short">Begin an edit. While in edit mode, no events are relayed to the containing store.</div>\r
141             <div class="long">\r
142                 Begin an edit. While in edit mode, no events are relayed to the containing store.    <div class="mdetail-params">\r
143         <strong>Parameters:</strong>\r
144         <ul><li>None.</li>        </ul>\r
145         <strong>Returns:</strong>\r
146         <ul>\r
147             <li><code>void</code></li>\r
148         </ul>\r
149     </div>\r
150                 </div>\r
151                         </div>\r
152         </td>\r
153         <td class="msource">Record</td>\r
154     </tr>\r
155         <tr class="method-row expandable">\r
156         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
157         <td class="sig">\r
158         <a id="Ext.data.Record-cancelEdit"></a>\r
159             <b>cancelEdit</b>() : void            <div class="mdesc">\r
160                         <div class="short">Cancels all changes made in the current edit operation.</div>\r
161             <div class="long">\r
162                 Cancels all changes made in the current edit operation.    <div class="mdetail-params">\r
163         <strong>Parameters:</strong>\r
164         <ul><li>None.</li>        </ul>\r
165         <strong>Returns:</strong>\r
166         <ul>\r
167             <li><code>void</code></li>\r
168         </ul>\r
169     </div>\r
170                 </div>\r
171                         </div>\r
172         </td>\r
173         <td class="msource">Record</td>\r
174     </tr>\r
175         <tr class="method-row alt expandable">\r
176         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
177         <td class="sig">\r
178         <a id="Ext.data.Record-commit"></a>\r
179             <b>commit</b>(&nbsp;<span class="optional" title="Optional">[<code>Boolean silent</code>]</span>&nbsp;) : void            <div class="mdesc">\r
180                         <div class="short">Usually called by the Ext.data.Store which owns the Record.
181 Commits all changes made to the Record since either creat...</div>\r
182             <div class="long">\r
183                 Usually called by the <a ext:cls="Ext.data.Store" href="output/Ext.data.Store.html">Ext.data.Store</a> which owns the Record.
184 Commits all changes made to the Record since either creation, or the last commit operation.
185 <p>
186 Developers should subscribe to the <a ext:cls="Ext.data.Store" ext:member="update" href="output/Ext.data.Store.html#update">Ext.data.Store.update</a> event to have their code notified
187 of commit operations.    <div class="mdetail-params">\r
188         <strong>Parameters:</strong>\r
189         <ul><li><code>silent</code> : Boolean<div class="sub-desc">(optional) True to skip notification of the owning store of the change (defaults to false)</div></li>        </ul>\r
190         <strong>Returns:</strong>\r
191         <ul>\r
192             <li><code>void</code></li>\r
193         </ul>\r
194     </div>\r
195                 </div>\r
196                         </div>\r
197         </td>\r
198         <td class="msource">Record</td>\r
199     </tr>\r
200         <tr class="method-row expandable">\r
201         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
202         <td class="sig">\r
203         <a id="Ext.data.Record-copy"></a>\r
204             <b>copy</b>(&nbsp;<span class="optional" title="Optional">[<code>String id</code>]</span>&nbsp;) : Record            <div class="mdesc">\r
205                         <div class="short">Creates a copy of this Record.</div>\r
206             <div class="long">\r
207                 Creates a copy of this Record.    <div class="mdetail-params">\r
208         <strong>Parameters:</strong>\r
209         <ul><li><code>id</code> : String<div class="sub-desc">(optional) A new Record id if you don't want to use this Record's id</div></li>        </ul>\r
210         <strong>Returns:</strong>\r
211         <ul>\r
212             <li><code>Record</code></li>\r
213         </ul>\r
214     </div>\r
215                 </div>\r
216                         </div>\r
217         </td>\r
218         <td class="msource">Record</td>\r
219     </tr>\r
220         <tr class="method-row alt expandable">\r
221         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
222         <td class="sig">\r
223         <a id="Ext.data.Record-create"></a>\r
224             <b>create</b>(&nbsp;<span class="optional" title="Optional">[<code>Array o</code>]</span>&nbsp;) : function            <div class="mdesc">\r
225                         <div class="short">&lt;static&gt; Generate a constructor for a specific Record layout.</div>\r
226             <div class="long">\r
227                 &lt;static&gt; Generate a constructor for a specific Record layout.    <div class="mdetail-params">\r
228         <strong>Parameters:</strong>\r
229         <ul><li><code>o</code> : Array<div class="sub-desc">An Array of field definition objects which specify field names, and optionally,
230 data types, and a mapping for an <a ext:cls="Ext.data.Reader" href="output/Ext.data.Reader.html">Ext.data.Reader</a> to extract the field's value from a data object.
231 Each field definition object may contain the following properties: <ul>
232 <li><b>name</b> : String<div class="sub-desc">The name by which the field is referenced within the Record. This is referenced by,
233 for example, the <em>dataIndex</em> property in column definition objects passed to <a ext:cls="Ext.grid.ColumnModel" href="output/Ext.grid.ColumnModel.html">Ext.grid.ColumnModel</a></div></li>
234 <li><b>mapping</b> : String<div class="sub-desc">(Optional) A path specification for use by the <a ext:cls="Ext.data.Reader" href="output/Ext.data.Reader.html">Ext.data.Reader</a> implementation
235 that is creating the Record to access the data value from the data object. If an <a ext:cls="Ext.data.JsonReader" href="output/Ext.data.JsonReader.html">Ext.data.JsonReader</a>
236 is being used, then this is a string containing the javascript expression to reference the data relative to
237 the Record item's root. If an <a ext:cls="Ext.data.XmlReader" href="output/Ext.data.XmlReader.html">Ext.data.XmlReader</a> is being used, this is an <a ext:cls="Ext.DomQuery" href="output/Ext.DomQuery.html">Ext.DomQuery</a> path
238 to the data item relative to the Record element. If the mapping expression is the same as the field name,
239 this may be omitted.</div></li>
240 <li><b>type</b> : String<div class="sub-desc">(Optional) The data type for conversion to displayable value. Possible values are
241 <ul><li>auto (Default, implies no conversion)</li>
242 <li>string</li>
243 <li>int</li>
244 <li>float</li>
245 <li>boolean</li>
246 <li>date</li></ul></div></li>
247 <li><b>sortType</b> : Function<div class="sub-desc">(Optional) A function which converts a Field's value to a comparable value
248 in order to ensure correct sort ordering. Predefined functions are provided in <a ext:cls="Ext.data.SortTypes" href="output/Ext.data.SortTypes.html">Ext.data.SortTypes</a>.</div></li>
249 <li><b>sortDir</b> : String<div class="sub-desc">(Optional) Initial direction to sort. "ASC" or "DESC"</div></li>
250 <li><b>convert</b> : Function<div class="sub-desc">(Optional) A function which converts the value provided
251 by the Reader into an object that will be stored in the Record. It is passed the
252 following parameters:<ul>
253 <li><b>v</b> : Mixed<div class="sub-desc">The data value as read by the Reader.</div></li>
254 <li><b>rec</b> : Mixed<div class="sub-desc">The data object containing the row as read by the Reader.
255 Depending on Reader type, this could be an Array, an object, or an XML element.</div></li>
256 </ul></div></li>
257 <li><b>dateFormat</b> : String<div class="sub-desc">(Optional) A format string for the <a ext:cls="Date" ext:member="parseDate" href="output/Date.html#parseDate">Date.parseDate</a> function,
258 or "timestamp" if the value provided by the Reader is a UNIX timestamp, or "time" if the value provided by the Reader is a 
259 javascript millisecond timestamp.</div></li>
260 <li><b>defaultValue</b> : Mixed<div class="sub-desc">(Optional) The default value used <b>when a Record is being created by a
261 <a ext:cls="Ext.data.Reader" href="output/Ext.data.Reader.html">Reader</a></b> when the item referenced by the <b><tt>mapping</tt></b> does not exist in the data object
262 (i.e. undefined). (defaults to "")</div></li>
263 </ul>
264 The constructor generated by this method may be used to create new Record instances. The data object must contain properties
265 named after the field <b>names</b>. 
266 <br>usage:<br><pre><code>var TopicRecord = Ext.data.Record.create([
267     {name: <em>'title'</em>, mapping: <em>'topic_title'</em>},
268     {name: <em>'author'</em>, mapping: <em>'username'</em>},
269     {name: <em>'totalPosts'</em>, mapping: <em>'topic_replies'</em>, type: <em>'int'</em>},
270     {name: <em>'lastPost'</em>, mapping: <em>'post_time'</em>, type: <em>'date'</em>},
271     {name: <em>'lastPoster'</em>, mapping: <em>'user2'</em>},
272     {name: <em>'excerpt'</em>, mapping: <em>'post_text'</em>}
273 ]);
274
275 <b>var</b> myNewRecord = <b>new</b> TopicRecord({
276     title: <em>'Do my job please'</em>,
277     author: <em>'noobie'</em>,
278     totalPosts: 1,
279     lastPost: <b>new</b> Date(),
280     lastPoster: <em>'Animal'</em>,
281     excerpt: <em>'No way dude!'</em>
282 });
283 myStore.add(myNewRecord);</code></pre>
284 <p>In the simplest case, if no properties other than <tt>name</tt> are required, a field definition
285 may consist of just a field name string.</p></div></li>        </ul>\r
286         <strong>Returns:</strong>\r
287         <ul>\r
288             <li><code>function</code><div class="sub-desc">A constructor which is used to create new Records according to the definition.</div></li>\r
289         </ul>\r
290     </div>\r
291                 </div>\r
292                         </div>\r
293         </td>\r
294         <td class="msource">Record</td>\r
295     </tr>\r
296         <tr class="method-row expandable">\r
297         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
298         <td class="sig">\r
299         <a id="Ext.data.Record-endEdit"></a>\r
300             <b>endEdit</b>() : void            <div class="mdesc">\r
301                         <div class="short">End an edit. If any data was modified, the containing store is notified.</div>\r
302             <div class="long">\r
303                 End an edit. If any data was modified, the containing store is notified.    <div class="mdetail-params">\r
304         <strong>Parameters:</strong>\r
305         <ul><li>None.</li>        </ul>\r
306         <strong>Returns:</strong>\r
307         <ul>\r
308             <li><code>void</code></li>\r
309         </ul>\r
310     </div>\r
311                 </div>\r
312                         </div>\r
313         </td>\r
314         <td class="msource">Record</td>\r
315     </tr>\r
316         <tr class="method-row alt expandable">\r
317         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
318         <td class="sig">\r
319         <a id="Ext.data.Record-get"></a>\r
320             <b>get</b>(&nbsp;<code>String name</code>&nbsp;) : Object            <div class="mdesc">\r
321                         <div class="short">Get the value of the named field.</div>\r
322             <div class="long">\r
323                 Get the value of the named field.    <div class="mdetail-params">\r
324         <strong>Parameters:</strong>\r
325         <ul><li><code>name</code> : String<div class="sub-desc">The name of the field to get the value of.</div></li>        </ul>\r
326         <strong>Returns:</strong>\r
327         <ul>\r
328             <li><code>Object</code><div class="sub-desc">The value of the field.</div></li>\r
329         </ul>\r
330     </div>\r
331                 </div>\r
332                         </div>\r
333         </td>\r
334         <td class="msource">Record</td>\r
335     </tr>\r
336         <tr class="method-row expandable">\r
337         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
338         <td class="sig">\r
339         <a id="Ext.data.Record-getChanges"></a>\r
340             <b>getChanges</b>() : Object            <div class="mdesc">\r
341                         <div class="short">Gets a hash of only the fields that have been modified since this Record was created or commited.</div>\r
342             <div class="long">\r
343                 Gets a hash of only the fields that have been modified since this Record was created or commited.    <div class="mdetail-params">\r
344         <strong>Parameters:</strong>\r
345         <ul><li>None.</li>        </ul>\r
346         <strong>Returns:</strong>\r
347         <ul>\r
348             <li><code>Object</code></li>\r
349         </ul>\r
350     </div>\r
351                 </div>\r
352                         </div>\r
353         </td>\r
354         <td class="msource">Record</td>\r
355     </tr>\r
356         <tr class="method-row alt expandable">\r
357         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
358         <td class="sig">\r
359         <a id="Ext.data.Record-isModified"></a>\r
360             <b>isModified</b>(&nbsp;<code>String fieldName</code>&nbsp;) : Boolean            <div class="mdesc">\r
361                         <div class="short">Returns true if the field passed has been modified since the load or last commit.</div>\r
362             <div class="long">\r
363                 Returns true if the field passed has been modified since the load or last commit.    <div class="mdetail-params">\r
364         <strong>Parameters:</strong>\r
365         <ul><li><code>fieldName</code> : String<div class="sub-desc"></div></li>        </ul>\r
366         <strong>Returns:</strong>\r
367         <ul>\r
368             <li><code>Boolean</code></li>\r
369         </ul>\r
370     </div>\r
371                 </div>\r
372                         </div>\r
373         </td>\r
374         <td class="msource">Record</td>\r
375     </tr>\r
376         <tr class="method-row expandable">\r
377         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
378         <td class="sig">\r
379         <a id="Ext.data.Record-reject"></a>\r
380             <b>reject</b>(&nbsp;<span class="optional" title="Optional">[<code>Boolean silent</code>]</span>&nbsp;) : void            <div class="mdesc">\r
381                         <div class="short">Usually called by the Ext.data.Store which owns the Record.
382 Rejects all changes made to the Record since either creat...</div>\r
383             <div class="long">\r
384                 Usually called by the <a ext:cls="Ext.data.Store" href="output/Ext.data.Store.html">Ext.data.Store</a> which owns the Record.
385 Rejects all changes made to the Record since either creation, or the last commit operation.
386 Modified fields are reverted to their original values.
387 <p>
388 Developers should subscribe to the <a ext:cls="Ext.data.Store" ext:member="update" href="output/Ext.data.Store.html#update">Ext.data.Store.update</a> event to have their code notified
389 of reject operations.    <div class="mdetail-params">\r
390         <strong>Parameters:</strong>\r
391         <ul><li><code>silent</code> : Boolean<div class="sub-desc">(optional) True to skip notification of the owning store of the change (defaults to false)</div></li>        </ul>\r
392         <strong>Returns:</strong>\r
393         <ul>\r
394             <li><code>void</code></li>\r
395         </ul>\r
396     </div>\r
397                 </div>\r
398                         </div>\r
399         </td>\r
400         <td class="msource">Record</td>\r
401     </tr>\r
402         <tr class="method-row alt expandable">\r
403         <td class="micon"><a class="exi" href="#expand">&nbsp;</a></td>\r
404         <td class="sig">\r
405         <a id="Ext.data.Record-set"></a>\r
406             <b>set</b>(&nbsp;<code>String name</code>, <code>Object value</code>&nbsp;) : void            <div class="mdesc">\r
407                         <div class="short">Set the named field to the specified value.</div>\r
408             <div class="long">\r
409                 Set the named field to the specified value.    <div class="mdetail-params">\r
410         <strong>Parameters:</strong>\r
411         <ul><li><code>name</code> : String<div class="sub-desc">The name of the field to set.</div></li><li><code>value</code> : Object<div class="sub-desc">The value to set the field to.</div></li>        </ul>\r
412         <strong>Returns:</strong>\r
413         <ul>\r
414             <li><code>void</code></li>\r
415         </ul>\r
416     </div>\r
417                 </div>\r
418                         </div>\r
419         </td>\r
420         <td class="msource">Record</td>\r
421     </tr>\r
422             </table>
423                 <a id="Ext.data.Record-events"></a>
424         <h2>Public Events</h2>
425         <div class="no-members">This class has no public events.</div>
426         </div>