Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / docs / source / Json.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-data-reader-Json'>/**
19 </span> * @author Ed Spencer
20  * @class Ext.data.reader.Json
21  * @extends Ext.data.reader.Reader
22  * 
23  * &lt;p&gt;The JSON Reader is used by a Proxy to read a server response that is sent back in JSON format. This usually
24  * happens as a result of loading a Store - for example we might create something like this:&lt;/p&gt;
25  * 
26 &lt;pre&gt;&lt;code&gt;
27 Ext.define('User', {
28     extend: 'Ext.data.Model',
29     fields: ['id', 'name', 'email']
30 });
31
32 var store = new Ext.data.Store({
33     model: 'User',
34     proxy: {
35         type: 'ajax',
36         url : 'users.json',
37         reader: {
38             type: 'json'
39         }
40     }
41 });
42 &lt;/code&gt;&lt;/pre&gt;
43  * 
44  * &lt;p&gt;The example above creates a 'User' model. Models are explained in the {@link Ext.data.Model Model} docs if you're
45  * not already familiar with them.&lt;/p&gt;
46  * 
47  * &lt;p&gt;We created the simplest type of JSON Reader possible by simply telling our {@link Ext.data.Store Store}'s 
48  * {@link Ext.data.proxy.Proxy Proxy} that we want a JSON Reader. The Store automatically passes the configured model to the
49  * Store, so it is as if we passed this instead:
50  * 
51 &lt;pre&gt;&lt;code&gt;
52 reader: {
53     type : 'json',
54     model: 'User'
55 }
56 &lt;/code&gt;&lt;/pre&gt;
57  * 
58  * &lt;p&gt;The reader we set up is ready to read data from our server - at the moment it will accept a response like this:&lt;/p&gt;
59  * 
60 &lt;pre&gt;&lt;code&gt;
61 [
62     {
63         &quot;id&quot;: 1,
64         &quot;name&quot;: &quot;Ed Spencer&quot;,
65         &quot;email&quot;: &quot;ed@sencha.com&quot;
66     },
67     {
68         &quot;id&quot;: 2,
69         &quot;name&quot;: &quot;Abe Elias&quot;,
70         &quot;email&quot;: &quot;abe@sencha.com&quot;
71     }
72 ]
73 &lt;/code&gt;&lt;/pre&gt;
74  * 
75  * &lt;p&gt;&lt;u&gt;Reading other JSON formats&lt;/u&gt;&lt;/p&gt;
76  * 
77  * &lt;p&gt;If you already have your JSON format defined and it doesn't look quite like what we have above, you can usually
78  * pass JsonReader a couple of configuration options to make it parse your format. For example, we can use the 
79  * {@link #root} configuration to parse data that comes back like this:&lt;/p&gt;
80  * 
81 &lt;pre&gt;&lt;code&gt;
82 {
83     &quot;users&quot;: [
84        {
85            &quot;id&quot;: 1,
86            &quot;name&quot;: &quot;Ed Spencer&quot;,
87            &quot;email&quot;: &quot;ed@sencha.com&quot;
88        },
89        {
90            &quot;id&quot;: 2,
91            &quot;name&quot;: &quot;Abe Elias&quot;,
92            &quot;email&quot;: &quot;abe@sencha.com&quot;
93        }
94     ]
95 }
96 &lt;/code&gt;&lt;/pre&gt;
97  * 
98  * &lt;p&gt;To parse this we just pass in a {@link #root} configuration that matches the 'users' above:&lt;/p&gt;
99  * 
100 &lt;pre&gt;&lt;code&gt;
101 reader: {
102     type: 'json',
103     root: 'users'
104 }
105 &lt;/code&gt;&lt;/pre&gt;
106  * 
107  * &lt;p&gt;Sometimes the JSON structure is even more complicated. Document databases like CouchDB often provide metadata
108  * around each record inside a nested structure like this:&lt;/p&gt;
109  * 
110 &lt;pre&gt;&lt;code&gt;
111 {
112     &quot;total&quot;: 122,
113     &quot;offset&quot;: 0,
114     &quot;users&quot;: [
115         {
116             &quot;id&quot;: &quot;ed-spencer-1&quot;,
117             &quot;value&quot;: 1,
118             &quot;user&quot;: {
119                 &quot;id&quot;: 1,
120                 &quot;name&quot;: &quot;Ed Spencer&quot;,
121                 &quot;email&quot;: &quot;ed@sencha.com&quot;
122             }
123         }
124     ]
125 }
126 &lt;/code&gt;&lt;/pre&gt;
127  * 
128  * &lt;p&gt;In the case above the record data is nested an additional level inside the &quot;users&quot; array as each &quot;user&quot; item has
129  * additional metadata surrounding it ('id' and 'value' in this case). To parse data out of each &quot;user&quot; item in the 
130  * JSON above we need to specify the {@link #record} configuration like this:&lt;/p&gt;
131  * 
132 &lt;pre&gt;&lt;code&gt;
133 reader: {
134     type  : 'json',
135     root  : 'users',
136     record: 'user'
137 }
138 &lt;/code&gt;&lt;/pre&gt;
139  * 
140  * &lt;p&gt;&lt;u&gt;Response metadata&lt;/u&gt;&lt;/p&gt;
141  * 
142  * &lt;p&gt;The server can return additional data in its response, such as the {@link #totalProperty total number of records} 
143  * and the {@link #successProperty success status of the response}. These are typically included in the JSON response
144  * like this:&lt;/p&gt;
145  * 
146 &lt;pre&gt;&lt;code&gt;
147 {
148     &quot;total&quot;: 100,
149     &quot;success&quot;: true,
150     &quot;users&quot;: [
151         {
152             &quot;id&quot;: 1,
153             &quot;name&quot;: &quot;Ed Spencer&quot;,
154             &quot;email&quot;: &quot;ed@sencha.com&quot;
155         }
156     ]
157 }
158 &lt;/code&gt;&lt;/pre&gt;
159  * 
160  * &lt;p&gt;If these properties are present in the JSON response they can be parsed out by the JsonReader and used by the
161  * Store that loaded it. We can set up the names of these properties by specifying a final pair of configuration 
162  * options:&lt;/p&gt;
163  * 
164 &lt;pre&gt;&lt;code&gt;
165 reader: {
166     type : 'json',
167     root : 'users',
168     totalProperty  : 'total',
169     successProperty: 'success'
170 }
171 &lt;/code&gt;&lt;/pre&gt;
172  * 
173  * &lt;p&gt;These final options are not necessary to make the Reader work, but can be useful when the server needs to report
174  * an error or if it needs to indicate that there is a lot of data available of which only a subset is currently being
175  * returned.&lt;/p&gt;
176  */
177 Ext.define('Ext.data.reader.Json', {
178     extend: 'Ext.data.reader.Reader',
179     alternateClassName: 'Ext.data.JsonReader',
180     alias : 'reader.json',
181     
182     root: '',
183     
184 <span id='Ext-data-reader-Json-cfg-record'>    /**
185 </span>     * @cfg {String} record The optional location within the JSON response that the record data itself can be found at.
186      * See the JsonReader intro docs for more details. This is not often needed and defaults to undefined.
187      */
188     
189 <span id='Ext-data-reader-Json-cfg-useSimpleAccessors'>    /**
190 </span>     * @cfg {Boolean} useSimpleAccessors True to ensure that field names/mappings are treated as literals when
191      * reading values. Defalts to &lt;tt&gt;false&lt;/tt&gt;.
192      * For example, by default, using the mapping &quot;foo.bar.baz&quot; will try and read a property foo from the root, then a property bar
193      * from foo, then a property baz from bar. Setting the simple accessors to true will read the property with the name 
194      * &quot;foo.bar.baz&quot; direct from the root object.
195      */
196     useSimpleAccessors: false,
197     
198 <span id='Ext-data-reader-Json-method-readRecords'>    /**
199 </span>     * Reads a JSON object and returns a ResultSet. Uses the internal getTotal and getSuccess extractors to
200      * retrieve meta data from the response, and extractData to turn the JSON data into model instances.
201      * @param {Object} data The raw JSON data
202      * @return {Ext.data.ResultSet} A ResultSet containing model instances and meta data about the results
203      */
204     readRecords: function(data) {
205         //this has to be before the call to super because we use the meta data in the superclass readRecords
206         if (data.metaData) {
207             this.onMetaChange(data.metaData);
208         }
209
210 <span id='Ext-data-reader-Json-property-jsonData'>        /**
211 </span>         * DEPRECATED - will be removed in Ext JS 5.0. This is just a copy of this.rawData - use that instead
212          * @property jsonData
213          * @type Mixed
214          */
215         this.jsonData = data;
216         return this.callParent([data]);
217     },
218
219     //inherit docs
220     getResponseData: function(response) {
221         try {
222             var data = Ext.decode(response.responseText);
223         }
224         catch (ex) {
225             Ext.Error.raise({
226                 response: response,
227                 json: response.responseText,
228                 parseError: ex,
229                 msg: 'Unable to parse the JSON returned by the server: ' + ex.toString()
230             });
231         }
232         //&lt;debug&gt;
233         if (!data) {
234             Ext.Error.raise('JSON object not found');
235         }
236         //&lt;/debug&gt;
237
238         return data;
239     },
240
241     //inherit docs
242     buildExtractors : function() {
243         var me = this;
244         
245         me.callParent(arguments);
246
247         if (me.root) {
248             me.getRoot = me.createAccessor(me.root);
249         } else {
250             me.getRoot = function(root) {
251                 return root;
252             };
253         }
254     },
255     
256 <span id='Ext-data-reader-Json-method-extractData'>    /**
257 </span>     * @private
258      * We're just preparing the data for the superclass by pulling out the record objects we want. If a {@link #record}
259      * was specified we have to pull those out of the larger JSON object, which is most of what this function is doing
260      * @param {Object} root The JSON root node
261      * @return {Array} The records
262      */
263     extractData: function(root) {
264         var recordName = this.record,
265             data = [],
266             length, i;
267         
268         if (recordName) {
269             length = root.length;
270             
271             for (i = 0; i &lt; length; i++) {
272                 data[i] = root[i][recordName];
273             }
274         } else {
275             data = root;
276         }
277         return this.callParent([data]);
278     },
279
280 <span id='Ext-data-reader-Json-method-createAccessor'>    /**
281 </span>     * @private
282      * Returns an accessor function for the given property string. Gives support for properties such as the following:
283      * 'someProperty'
284      * 'some.property'
285      * 'some[&quot;property&quot;]'
286      * This is used by buildExtractors to create optimized extractor functions when casting raw data into model instances.
287      */
288     createAccessor: function() {
289         var re = /[\[\.]/;
290         
291         return function(expr) {
292             if (Ext.isEmpty(expr)) {
293                 return Ext.emptyFn;
294             }
295             if (Ext.isFunction(expr)) {
296                 return expr;
297             }
298             if (this.useSimpleAccessors !== true) {
299                 var i = String(expr).search(re);
300                 if (i &gt;= 0) {
301                     return Ext.functionFactory('obj', 'return obj' + (i &gt; 0 ? '.' : '') + expr);
302                 }
303             }
304             return function(obj) {
305                 return obj[expr];
306             };
307         };
308     }()
309 });</pre>
310 </body>
311 </html>