projects / roojs1 / blob
? search:


e566c1adf9a2aae850a8c5caea1d0f95056965be
[roojs1] / docs / src / Roo_data_Record.js.html
1 <html><head><title>Roo/data/Record.js</title><link rel="stylesheet" type="text/css" href="../../css/highlight-js.css"/></head><body class="highlightpage"><code class="jsdoc-pretty"><span class="jsdoc-comment">/*
2  * Based on:
3  * Ext JS Library 1.1.1
4  * Copyright(c) 2006-2007, Ext JS, LLC.
5  *
6  * Originally Released Under LGPL - original licence link has changed is not relivant.
7  *
8  * Fork - LGPL
9  * &lt;script type=&quot;text/javascript&quot;&gt;
10  */
11
12 /**
13 * @class Roo.data.Record
14  * Instances of this class encapsulate both record &lt;em&gt;definition&lt;/em&gt; information, and record
15  * &lt;em&gt;value&lt;/em&gt; information for use in {@link Roo.data.Store} objects, or any code which needs
16  * to access Records cached in an {@link Roo.data.Store} object.&lt;br&gt;
17  * &lt;p&gt;
18  * Constructors for this class are generated by passing an Array of field definition objects to {@link #create}.
19  * Instances are usually only created by {@link Roo.data.Reader} implementations when processing unformatted data
20  * objects.&lt;br&gt;
21  * &lt;p&gt;
22  * Record objects generated by this constructor inherit all the methods of Roo.data.Record listed below.
23  * @constructor
24  * This constructor should not be used to create Record objects. Instead, use the constructor generated by
25  * {@link #create}. The parameters are the same.
26  * @param {Array} data An associative Array of data values keyed by the field name.
27  * @param {Object} id (Optional) The id of the record. This id should be unique, and is used by the
28  * {@link Roo.data.Store} object which owns the Record to index its collection of Records. If
29  * not specified an integer id is generated.
30  */
31 </span><span class="jsdoc-var">Roo.data.Record </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">data</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">id</span><span class="jsdoc-syntax">){
32     </span><span class="jsdoc-var">this.id </span><span class="jsdoc-syntax">= (</span><span class="jsdoc-var">id </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">id </span><span class="jsdoc-syntax">=== 0) ? </span><span class="jsdoc-var">id </span><span class="jsdoc-syntax">: ++</span><span class="jsdoc-var">Roo.data.Record.AUTO_ID</span><span class="jsdoc-syntax">;
33     </span><span class="jsdoc-var">this.data </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">data</span><span class="jsdoc-syntax">;
34 };
35
36 </span><span class="jsdoc-comment">/**
37  * Generate a constructor for a specific record layout.
38  * @param {Array} o An Array of field definition objects which specify field names, and optionally,
39  * data types, and a mapping for an {@link Roo.data.Reader} to extract the field's value from a data object.
40  * Each field definition object may contain the following properties: &lt;ul&gt;
41  * &lt;li&gt;&lt;b&gt;name&lt;/b&gt; : String&lt;p style=&quot;margin-left:1em&quot;&gt;The name by which the field is referenced within the Record. This is referenced by,
42  * for example the &lt;em&gt;dataIndex&lt;/em&gt; property in column definition objects passed to {@link Roo.grid.ColumnModel}&lt;/p&gt;&lt;/li&gt;
43  * &lt;li&gt;&lt;b&gt;mapping&lt;/b&gt; : String&lt;p style=&quot;margin-left:1em&quot;&gt;(Optional) A path specification for use by the {@link Roo.data.Reader} implementation
44  * that is creating the Record to access the data value from the data object. If an {@link Roo.data.JsonReader}
45  * is being used, then this is a string containing the javascript expression to reference the data relative to 
46  * the record item's root. If an {@link Roo.data.XmlReader} is being used, this is an {@link Roo.DomQuery} path
47  * to the data item relative to the record element. If the mapping expression is the same as the field name,
48  * this may be omitted.&lt;/p&gt;&lt;/li&gt;
49  * &lt;li&gt;&lt;b&gt;type&lt;/b&gt; : String&lt;p style=&quot;margin-left:1em&quot;&gt;(Optional) The data type for conversion to displayable value. Possible values are
50  * &lt;ul&gt;&lt;li&gt;auto (Default, implies no conversion)&lt;/li&gt;
51  * &lt;li&gt;string&lt;/li&gt;
52  * &lt;li&gt;int&lt;/li&gt;
53  * &lt;li&gt;float&lt;/li&gt;
54  * &lt;li&gt;boolean&lt;/li&gt;
55  * &lt;li&gt;date&lt;/li&gt;&lt;/ul&gt;&lt;/p&gt;&lt;/li&gt;
56  * &lt;li&gt;&lt;b&gt;sortType&lt;/b&gt; : Mixed&lt;p style=&quot;margin-left:1em&quot;&gt;(Optional) A member of {@link Roo.data.SortTypes}.&lt;/p&gt;&lt;/li&gt;
57  * &lt;li&gt;&lt;b&gt;sortDir&lt;/b&gt; : String&lt;p style=&quot;margin-left:1em&quot;&gt;(Optional) Initial direction to sort. &quot;ASC&quot; or &quot;DESC&quot;&lt;/p&gt;&lt;/li&gt;
58  * &lt;li&gt;&lt;b&gt;convert&lt;/b&gt; : Function&lt;p style=&quot;margin-left:1em&quot;&gt;(Optional) A function which converts the value provided
59  * by the Reader into an object that will be stored in the Record. It is passed the
60  * following parameters:&lt;ul&gt;
61  * &lt;li&gt;&lt;b&gt;v&lt;/b&gt; : Mixed&lt;p style=&quot;margin-left:1em&quot;&gt;The data value as read by the Reader.&lt;/p&gt;&lt;/li&gt;
62  * &lt;/ul&gt;&lt;/p&gt;&lt;/li&gt;
63  * &lt;li&gt;&lt;b&gt;dateFormat&lt;/b&gt; : String&lt;p style=&quot;margin-left:1em&quot;&gt;(Optional) A format String for the Date.parseDate function.&lt;/p&gt;&lt;/li&gt;
64  * &lt;/ul&gt;
65  * &lt;br&gt;usage:&lt;br&gt;&lt;pre&gt;&lt;code&gt;
66 var TopicRecord = Roo.data.Record.create(
67     {name: 'title', mapping: 'topic_title'},
68     {name: 'author', mapping: 'username'},
69     {name: 'totalPosts', mapping: 'topic_replies', type: 'int'},
70     {name: 'lastPost', mapping: 'post_time', type: 'date'},
71     {name: 'lastPoster', mapping: 'user2'},
72     {name: 'excerpt', mapping: 'post_text'}
73 );
74
75 var myNewRecord = new TopicRecord({
76     title: 'Do my job please',
77     author: 'noobie',
78     totalPosts: 1,
79     lastPost: new Date(),
80     lastPoster: 'Animal',
81     excerpt: 'No way dude!'
82 });
83 myStore.add(myNewRecord);
84 &lt;/code&gt;&lt;/pre&gt;
85  * @method create
86  * @static
87  */
88 </span><span class="jsdoc-var">Roo.data.Record.create </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">o</span><span class="jsdoc-syntax">){
89     </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">f </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
90         </span><span class="jsdoc-var">f.superclass.constructor.apply</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">arguments</span><span class="jsdoc-syntax">);
91     };
92     </span><span class="jsdoc-var">Roo.extend</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">f</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">Roo.data.Record</span><span class="jsdoc-syntax">);
93     </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">p </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">f.prototype</span><span class="jsdoc-syntax">;
94     </span><span class="jsdoc-var">p.fields </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">new </span><span class="jsdoc-var">Roo.util.MixedCollection</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">, </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">field</span><span class="jsdoc-syntax">){
95         </span><span class="jsdoc-keyword">return </span><span class="jsdoc-var">field.name</span><span class="jsdoc-syntax">;
96     });
97     </span><span class="jsdoc-keyword">for</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">= 0, </span><span class="jsdoc-var">len </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">o.length</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">&lt; </span><span class="jsdoc-var">len</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">++){
98         </span><span class="jsdoc-var">p.fields.add</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">new </span><span class="jsdoc-var">Roo.data.Field</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">o</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">]));
99     }
100     </span><span class="jsdoc-var">f.getField </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">){
101         </span><span class="jsdoc-keyword">return </span><span class="jsdoc-var">p.fields.get</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">);
102     };
103     </span><span class="jsdoc-keyword">return </span><span class="jsdoc-var">f</span><span class="jsdoc-syntax">;
104 };
105
106 </span><span class="jsdoc-var">Roo.data.Record.AUTO_ID </span><span class="jsdoc-syntax">= 1000;
107 </span><span class="jsdoc-var">Roo.data.Record.EDIT </span><span class="jsdoc-syntax">= </span><span class="jsdoc-string">'edit'</span><span class="jsdoc-syntax">;
108 </span><span class="jsdoc-var">Roo.data.Record.REJECT </span><span class="jsdoc-syntax">= </span><span class="jsdoc-string">'reject'</span><span class="jsdoc-syntax">;
109 </span><span class="jsdoc-var">Roo.data.Record.COMMIT </span><span class="jsdoc-syntax">= </span><span class="jsdoc-string">'commit'</span><span class="jsdoc-syntax">;
110
111 </span><span class="jsdoc-var">Roo.data.Record.prototype </span><span class="jsdoc-syntax">= {
112     </span><span class="jsdoc-comment">/**
113      * Readonly flag - true if this record has been modified.
114      * @type Boolean
115      */
116     </span><span class="jsdoc-var">dirty </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">,
117     </span><span class="jsdoc-var">editing </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">,
118     </span><span class="jsdoc-var">error</span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">null</span><span class="jsdoc-syntax">,
119     </span><span class="jsdoc-var">modified</span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">null</span><span class="jsdoc-syntax">,
120
121     </span><span class="jsdoc-comment">// private
122     </span><span class="jsdoc-var">join </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">store</span><span class="jsdoc-syntax">){
123         </span><span class="jsdoc-var">this.store </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">store</span><span class="jsdoc-syntax">;
124     },
125
126     </span><span class="jsdoc-comment">/**
127      * Set the named field to the specified value.
128      * @param {String} name The name of the field to set.
129      * @param {Object} value The value to set the field to.
130      */
131     </span><span class="jsdoc-var">set </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">value</span><span class="jsdoc-syntax">){
132         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.data</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">] == </span><span class="jsdoc-var">value</span><span class="jsdoc-syntax">){
133             </span><span class="jsdoc-keyword">return</span><span class="jsdoc-syntax">;
134         }
135         </span><span class="jsdoc-var">this.dirty </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">true</span><span class="jsdoc-syntax">;
136         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(!</span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">){
137             </span><span class="jsdoc-var">this.modified </span><span class="jsdoc-syntax">= {};
138         }
139         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">typeof </span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">] == </span><span class="jsdoc-string">'undefined'</span><span class="jsdoc-syntax">){
140             </span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">] = </span><span class="jsdoc-var">this.data</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">];
141         }
142         </span><span class="jsdoc-var">this.data</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">] = </span><span class="jsdoc-var">value</span><span class="jsdoc-syntax">;
143         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(!</span><span class="jsdoc-var">this.editing </span><span class="jsdoc-syntax">&amp;&amp; </span><span class="jsdoc-var">this.store</span><span class="jsdoc-syntax">){
144             </span><span class="jsdoc-var">this.store.afterEdit</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">);
145         }
146     },
147
148     </span><span class="jsdoc-comment">/**
149      * Get the value of the named field.
150      * @param {String} name The name of the field to get the value of.
151      * @return {Object} The value of the field.
152      */
153     </span><span class="jsdoc-var">get </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">){
154         </span><span class="jsdoc-keyword">return </span><span class="jsdoc-var">this.data</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">name</span><span class="jsdoc-syntax">];
155     },
156
157     </span><span class="jsdoc-comment">// private
158     </span><span class="jsdoc-var">beginEdit </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
159         </span><span class="jsdoc-var">this.editing </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">true</span><span class="jsdoc-syntax">;
160         </span><span class="jsdoc-var">this.modified </span><span class="jsdoc-syntax">= {};
161     },
162
163     </span><span class="jsdoc-comment">// private
164     </span><span class="jsdoc-var">cancelEdit </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
165         </span><span class="jsdoc-var">this.editing </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
166         </span><span class="jsdoc-keyword">delete </span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">;
167     },
168
169     </span><span class="jsdoc-comment">// private
170     </span><span class="jsdoc-var">endEdit </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
171         </span><span class="jsdoc-var">this.editing </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
172         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.dirty </span><span class="jsdoc-syntax">&amp;&amp; </span><span class="jsdoc-var">this.store</span><span class="jsdoc-syntax">){
173             </span><span class="jsdoc-var">this.store.afterEdit</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">);
174         }
175     },
176
177     </span><span class="jsdoc-comment">/**
178      * Usually called by the {@link Roo.data.Store} which owns the Record.
179      * Rejects all changes made to the Record since either creation, or the last commit operation.
180      * Modified fields are reverted to their original values.
181      * &lt;p&gt;
182      * Developers should subscribe to the {@link Roo.data.Store#update} event to have their code notified
183      * of reject operations.
184      */
185     </span><span class="jsdoc-var">reject </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
186         </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">m </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">;
187         </span><span class="jsdoc-keyword">for</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">n </span><span class="jsdoc-keyword">in </span><span class="jsdoc-var">m</span><span class="jsdoc-syntax">){
188             </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">typeof </span><span class="jsdoc-var">m</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">n</span><span class="jsdoc-syntax">] != </span><span class="jsdoc-string">&quot;function&quot;</span><span class="jsdoc-syntax">){
189                 </span><span class="jsdoc-var">this.data</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">n</span><span class="jsdoc-syntax">] = </span><span class="jsdoc-var">m</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">n</span><span class="jsdoc-syntax">];
190             }
191         }
192         </span><span class="jsdoc-var">this.dirty </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
193         </span><span class="jsdoc-keyword">delete </span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">;
194         </span><span class="jsdoc-var">this.editing </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
195         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.store</span><span class="jsdoc-syntax">){
196             </span><span class="jsdoc-var">this.store.afterReject</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">);
197         }
198     },
199
200     </span><span class="jsdoc-comment">/**
201      * Usually called by the {@link Roo.data.Store} which owns the Record.
202      * Commits all changes made to the Record since either creation, or the last commit operation.
203      * &lt;p&gt;
204      * Developers should subscribe to the {@link Roo.data.Store#update} event to have their code notified
205      * of commit operations.
206      */
207     </span><span class="jsdoc-var">commit </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
208         </span><span class="jsdoc-var">this.dirty </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
209         </span><span class="jsdoc-keyword">delete </span><span class="jsdoc-var">this.modified</span><span class="jsdoc-syntax">;
210         </span><span class="jsdoc-var">this.editing </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
211         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.store</span><span class="jsdoc-syntax">){
212             </span><span class="jsdoc-var">this.store.afterCommit</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">);
213         }
214     },
215
216     </span><span class="jsdoc-comment">// private
217     </span><span class="jsdoc-var">hasError </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
218         </span><span class="jsdoc-keyword">return </span><span class="jsdoc-var">this.error </span><span class="jsdoc-syntax">!= </span><span class="jsdoc-keyword">null</span><span class="jsdoc-syntax">;
219     },
220
221     </span><span class="jsdoc-comment">// private
222     </span><span class="jsdoc-var">clearError </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
223         </span><span class="jsdoc-var">this.error </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">null</span><span class="jsdoc-syntax">;
224     },
225
226     </span><span class="jsdoc-comment">/**
227      * Creates a copy of this record.
228      * @param {String} id (optional) A new record id if you don't want to use this record's id
229      * @return {Record}
230      */
231     </span><span class="jsdoc-var">copy </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">newId</span><span class="jsdoc-syntax">) {
232         </span><span class="jsdoc-keyword">return new </span><span class="jsdoc-var">this.constructor</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">Roo.apply</span><span class="jsdoc-syntax">({}, </span><span class="jsdoc-var">this.data</span><span class="jsdoc-syntax">), </span><span class="jsdoc-var">newId </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">this.id</span><span class="jsdoc-syntax">);
233     }
234 };</span></code></body></html>
RooJS - Version 1