/ext-4.0.7/docs/source/Json.html
HTML | 316 lines | 299 code | 17 blank | 0 comment | 0 complexity | a82d6ef8d5b66073d1e83d7ba498627c MD5 | raw file
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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7 <script type="text/javascript" src="../resources/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 * <p>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:</p>
25 *
26<pre><code>
27Ext.define('User', {
28 extend: 'Ext.data.Model',
29 fields: ['id', 'name', 'email']
30});
31
32var store = Ext.create('Ext.data.Store', {
33 model: 'User',
34 proxy: {
35 type: 'ajax',
36 url : 'users.json',
37 reader: {
38 type: 'json'
39 }
40 }
41});
42</code></pre>
43 *
44 * <p>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.</p>
46 *
47 * <p>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<pre><code>
52reader: {
53 type : 'json',
54 model: 'User'
55}
56</code></pre>
57 *
58 * <p>The reader we set up is ready to read data from our server - at the moment it will accept a response like this:</p>
59 *
60<pre><code>
61[
62 {
63 "id": 1,
64 "name": "Ed Spencer",
65 "email": "ed@sencha.com"
66 },
67 {
68 "id": 2,
69 "name": "Abe Elias",
70 "email": "abe@sencha.com"
71 }
72]
73</code></pre>
74 *
75 * <p><u>Reading other JSON formats</u></p>
76 *
77 * <p>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:</p>
80 *
81<pre><code>
82{
83 "users": [
84 {
85 "id": 1,
86 "name": "Ed Spencer",
87 "email": "ed@sencha.com"
88 },
89 {
90 "id": 2,
91 "name": "Abe Elias",
92 "email": "abe@sencha.com"
93 }
94 ]
95}
96</code></pre>
97 *
98 * <p>To parse this we just pass in a {@link #root} configuration that matches the 'users' above:</p>
99 *
100<pre><code>
101reader: {
102 type: 'json',
103 root: 'users'
104}
105</code></pre>
106 *
107 * <p>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:</p>
109 *
110<pre><code>
111{
112 "total": 122,
113 "offset": 0,
114 "users": [
115 {
116 "id": "ed-spencer-1",
117 "value": 1,
118 "user": {
119 "id": 1,
120 "name": "Ed Spencer",
121 "email": "ed@sencha.com"
122 }
123 }
124 ]
125}
126</code></pre>
127 *
128 * <p>In the case above the record data is nested an additional level inside the "users" array as each "user" item has
129 * additional metadata surrounding it ('id' and 'value' in this case). To parse data out of each "user" item in the
130 * JSON above we need to specify the {@link #record} configuration like this:</p>
131 *
132<pre><code>
133reader: {
134 type : 'json',
135 root : 'users',
136 record: 'user'
137}
138</code></pre>
139 *
140 * <p><u>Response metadata</u></p>
141 *
142 * <p>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:</p>
145 *
146<pre><code>
147{
148 "total": 100,
149 "success": true,
150 "users": [
151 {
152 "id": 1,
153 "name": "Ed Spencer",
154 "email": "ed@sencha.com"
155 }
156 ]
157}
158</code></pre>
159 *
160 * <p>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:</p>
163 *
164<pre><code>
165reader: {
166 type : 'json',
167 root : 'users',
168 totalProperty : 'total',
169 successProperty: 'success'
170}
171</code></pre>
172 *
173 * <p>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.</p>
176 */
177Ext.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.
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 <tt>false</tt>.
192 * For example, by default, using the mapping "foo.bar.baz" 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 * "foo.bar.baz" 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 {Object} jsonData
213 */
214 this.jsonData = data;
215 return this.callParent([data]);
216 },
217
218 //inherit docs
219 getResponseData: function(response) {
220 var data;
221 try {
222 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 //<debug>
233 if (!data) {
234 Ext.Error.raise('JSON object not found');
235 }
236 //</debug>
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 {Ext.data.Model[]} 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 if (!length && Ext.isObject(root)) {
272 length = 1;
273 root = [root];
274 }
275
276 for (i = 0; i < length; i++) {
277 data[i] = root[i][recordName];
278 }
279 } else {
280 data = root;
281 }
282 return this.callParent([data]);
283 },
284
285<span id='Ext-data-reader-Json-method-createAccessor'> /**
286</span> * @private
287 * Returns an accessor function for the given property string. Gives support for properties such as the following:
288 * 'someProperty'
289 * 'some.property'
290 * 'some["property"]'
291 * This is used by buildExtractors to create optimized extractor functions when casting raw data into model instances.
292 */
293 createAccessor: function() {
294 var re = /[\[\.]/;
295
296 return function(expr) {
297 if (Ext.isEmpty(expr)) {
298 return Ext.emptyFn;
299 }
300 if (Ext.isFunction(expr)) {
301 return expr;
302 }
303 if (this.useSimpleAccessors !== true) {
304 var i = String(expr).search(re);
305 if (i >= 0) {
306 return Ext.functionFactory('obj', 'return obj' + (i > 0 ? '.' : '') + expr);
307 }
308 }
309 return function(obj) {
310 return obj[expr];
311 };
312 };
313 }()
314});</pre>
315</body>
316</html>