Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / api / Ext.data.reader.Json.html
1 <!DOCTYPE html><html><head><title>Ext.data.reader.Json | Ext JS 4.0 Documentation</title><script type="text/javascript" src="../ext-all.js"></script><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../scrollbars.css" type="text/css"><link rel="stylesheet" href="../docs.css" type="text/css"><link id="styleCss" rel="stylesheet" href="../style.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script><link rel="stylesheet" href="../prettify.css" type="text/css"><!-- link(rel: 'stylesheet', href: req.baseURL + '/css/ext4.css', type: 'text/css')--><link rel="shortcut icon" type="image/ico" href="../favicon.ico"><!--[if IE]>
2 <style type="text/css">.head-band { display: none; }
3 .header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
4 .doc-tab .members .member a.more { background-color: #efefef; }
5 </style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
6 </head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit 
7 <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a></div><div class="wrapper"><div class="head-band"></div><div class="header"><h2><a href="../index.html">Sencha Documentation</a></h2></div><div id="search"><form><input type="text" placeholder="Search" id="search-field" autocomplete="off" name="q"></form><div id="search-box"></div></div><div id="treePanel"></div><div id="container"><script type="text/javascript">
8
9     req = {
10         liveURL: '.',
11         standAloneMode: true,
12         origDocClass: 'Ext.data.reader.Json',
13         docClass: 'Ext.data.reader.Json',
14         docReq: 'Ext.data.reader.Json',
15         version: '4.0',
16         baseURL: '.',
17         baseDocURL: '.',
18         baseProdURL: '.'
19     };
20
21     clsInfo = {};
22
23
24
25 </script>
26
27 <script type="text/javascript" src="../search.js"></script>
28 <!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
29 <script type="text/javascript" src="../class_tree.js"></script>
30 <script type="text/javascript" src="../class_doc.js"></script>
31 <script type="text/javascript">
32     req.source = 'Json.html#Ext-data.reader.Json';
33     clsInfo = {"methods":["Json","getResponseData","read","readRecords"],"cfgs":["idProperty","implicitIncludes","messageProperty","record","root","successProperty","totalProperty","useSimpleAccessors"],"properties":["jsonData","rawData"],"events":[],"subclasses":["Ext.data.reader.Array"]};
34     Ext.onReady(function() {
35         Ext.create('Docs.classPanel');
36     });
37 </script><div id="top-block" class="top-block"><h1 id="clsTitle" class="cls"><a href="../source/Json.html#Ext-data.reader.Json" target="_blank">Ext.data.reader.Json</a></h1></div><div id="docContent"><div id="doc-overview-content"><div class="lft"><pre class="subclasses"><h4>Hierarchy</h4><div class="subclass f"><a href="Ext.data.reader.Reader.html" rel="Ext.data.reader.Reader" class="cls docClass">Ext.data.reader.Reader</a><div class="subclass"><strong>Ext.data.reader.Json</strong></div></div></pre><p>The JSON Reader is used by a Proxy to read a server response that is sent back in JSON format. This usually
38 happens as a result of loading a Store - for example we might create something like this:</p>
39
40
41
42
43 <pre class="prettyprint"><code>Ext.define('User', {
44     extend: 'Ext.data.Model',
45     fields: ['id', 'name', 'email']
46 });
47
48 var store = new Ext.data.Store({
49     model: 'User',
50     proxy: {
51         type: 'ajax',
52         url : 'users.json',
53         reader: {
54             type: 'json'
55         }
56     }
57 });
58 </code></pre>
59
60
61
62
63 <p>The example above creates a 'User' model. Models are explained in the <a href="Ext.data.Model.html" rel="Ext.data.Model" class="docClass">Model</a> docs if you're
64 not already familiar with them.</p>
65
66
67
68
69 <p>We created the simplest type of JSON Reader possible by simply telling our <a href="Ext.data.Store.html" rel="Ext.data.Store" class="docClass">Store</a>'s 
70 <a href="Ext.data.proxy.Proxy.html" rel="Ext.data.proxy.Proxy" class="docClass">Proxy</a> that we want a JSON Reader. The Store automatically passes the configured model to the
71 Store, so it is as if we passed this instead:
72
73 <pre class="prettyprint"><code>reader: {
74     type : 'json',
75     model: 'User'
76 }
77 </code></pre>
78
79 <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>
80
81 <pre class="prettyprint"><code>[
82     {
83         "id": 1,
84         "name": "Ed Spencer",
85         "email": "ed@sencha.com"
86     },
87     {
88         "id": 2,
89         "name": "Abe Elias",
90         "email": "abe@sencha.com"
91     }
92 ]
93 </code></pre>
94
95 <p><u>Reading other JSON formats</u></p>
96
97 <p>If you already have your JSON format defined and it doesn't look quite like what we have above, you can usually
98 pass JsonReader a couple of configuration options to make it parse your format. For example, we can use the 
99 <a href="Ext.data.reader.Json.html#root" rel="Ext.data.reader.Json#root" class="docClass">root</a> configuration to parse data that comes back like this:</p>
100
101 <pre class="prettyprint"><code>{
102     "users": [
103        {
104            "id": 1,
105            "name": "Ed Spencer",
106            "email": "ed@sencha.com"
107        },
108        {
109            "id": 2,
110            "name": "Abe Elias",
111            "email": "abe@sencha.com"
112        }
113     ]
114 }
115 </code></pre>
116
117 <p>To parse this we just pass in a <a href="Ext.data.reader.Json.html#root" rel="Ext.data.reader.Json#root" class="docClass">root</a> configuration that matches the 'users' above:</p>
118
119 <pre class="prettyprint"><code>reader: {
120     type: 'json',
121     root: 'users'
122 }
123 </code></pre>
124
125 <p>Sometimes the JSON structure is even more complicated. Document databases like CouchDB often provide metadata
126 around each record inside a nested structure like this:</p>
127
128 <pre class="prettyprint"><code>{
129     "total": 122,
130     "offset": 0,
131     "users": [
132         {
133             "id": "ed-spencer-1",
134             "value": 1,
135             "user": {
136                 "id": 1,
137                 "name": "Ed Spencer",
138                 "email": "ed@sencha.com"
139             }
140         }
141     ]
142 }
143 </code></pre>
144
145 <p>In the case above the record data is nested an additional level inside the "users" array as each "user" item has
146 additional metadata surrounding it ('id' and 'value' in this case). To parse data out of each "user" item in the 
147 JSON above we need to specify the <a href="Ext.data.reader.Json.html#record" rel="Ext.data.reader.Json#record" class="docClass">record</a> configuration like this:</p>
148
149 <pre class="prettyprint"><code>reader: {
150     type  : 'json',
151     root  : 'users',
152     record: 'user'
153 }
154 </code></pre>
155
156 <p><u>Response metadata</u></p>
157
158 <p>The server can return additional data in its response, such as the <a href="Ext.data.reader.Json.html#totalProperty" rel="Ext.data.reader.Json#totalProperty" class="docClass">total number of records</a> 
159 and the <a href="Ext.data.reader.Json.html#successProperty" rel="Ext.data.reader.Json#successProperty" class="docClass">success status of the response</a>. These are typically included in the JSON response
160 like this:</p>
161
162 <pre class="prettyprint"><code>{
163     "total": 100,
164     "success": true,
165     "users": [
166         {
167             "id": 1,
168             "name": "Ed Spencer",
169             "email": "ed@sencha.com"
170         }
171     ]
172 }
173 </code></pre>
174
175 <p>If these properties are present in the JSON response they can be parsed out by the JsonReader and used by the
176 Store that loaded it. We can set up the names of these properties by specifying a final pair of configuration 
177 options:</p>
178
179 <pre class="prettyprint"><code>reader: {
180     type : 'json',
181     root : 'users',
182     totalProperty  : 'total',
183     successProperty: 'success'
184 }
185 </code></pre>
186
187 <p>These final options are not necessary to make the Reader work, but can be useful when the server needs to report
188 an error or if it needs to indicate that there is a lot of data available of which only a subset is currently being
189 returned.</p>
190
191 <div class="members"><div class="m-cfgs"><div class="definedBy">Defined By</div><a name="configs"></a><h3 class="cfg p">Config Options</h3><h4 class="cfgGroup">Other Configs</h4><div id="config-idProperty" class="member f inherited"><a href="Ext.data.reader.Json.html#config-idProperty" rel="config-idProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-idProperty" class="viewSource">view source</a></div><a name="idProperty"></a><a name="config-idProperty"></a><a href="Ext.data.reader.Json.html#" rel="config-idProperty" class="cls expand">idProperty</a><span> : String</span></div><div class="description"><div class="short">Name of the property within a row object
192 that contains a record identifier value.  Defaults to The id of the model.
193 I...</div><div class="long"><p>Name of the property within a row object
194 that contains a record identifier value.  Defaults to <tt>The id of the model</tt>.
195 If an idProperty is explicitly specified it will override that of the one specified
196 on the model</p>
197 </div></div></div><div id="config-implicitIncludes" class="member inherited"><a href="Ext.data.reader.Json.html#config-implicitIncludes" rel="config-implicitIncludes" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-implicitIncludes" class="viewSource">view source</a></div><a name="implicitIncludes"></a><a name="config-implicitIncludes"></a><a href="Ext.data.reader.Json.html#" rel="config-implicitIncludes" class="cls expand">implicitIncludes</a><span> : Boolean</span></div><div class="description"><div class="short">True to automatically parse models nested within other models in a response
198 object. See the Ext.data.reader.Reader in...</div><div class="long"><p>True to automatically parse models nested within other models in a response
199 object. See the <a href="Ext.data.reader.Reader.html" rel="Ext.data.reader.Reader" class="docClass">Ext.data.reader.Reader</a> intro docs for full explanation. Defaults to true.</p>
200 </div></div></div><div id="config-messageProperty" class="member inherited"><a href="Ext.data.reader.Json.html#config-messageProperty" rel="config-messageProperty" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-messageProperty" class="viewSource">view source</a></div><a name="messageProperty"></a><a name="config-messageProperty"></a><a href="Ext.data.reader.Json.html#" rel="config-messageProperty" class="cls expand">messageProperty</a><span> : String</span></div><div class="description"><div class="short"><p>The name of the property which contains a response message.
201 This property is optional.</p>
202 </div><div class="long"><p>The name of the property which contains a response message.
203 This property is optional.</p>
204 </div></div></div><div id="config-record" class="member ni"><a href="Ext.data.reader.Json.html#config-record" rel="config-record" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Json.html" class="definedIn docClass">Ext.data.reader.Json</a><br/><a href="../source/Json.html#Ext-data.reader.Json-cfg-record" class="viewSource">view source</a></div><a name="record"></a><a name="config-record"></a><a href="Ext.data.reader.Json.html#" rel="config-record" class="cls expand">record</a><span> : String</span></div><div class="description"><div class="short">The optional location within the JSON response that the record data itself can be found at.
205 See the JsonReader intro ...</div><div class="long"><p>The optional location within the JSON response that the record data itself can be found at.
206 See the JsonReader intro docs for more details. This is not often needed and defaults to undefined.</p>
207 </div></div></div><div id="config-root" class="member inherited"><a href="Ext.data.reader.Json.html#config-root" rel="config-root" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-root" class="viewSource">view source</a></div><a name="root"></a><a name="config-root"></a><a href="Ext.data.reader.Json.html#" rel="config-root" class="cls expand">root</a><span> : String</span></div><div class="description"><div class="short">Required.  The name of the property
208 which contains the Array of row objects.  Defaults to undefined.
209 An exception wil...</div><div class="long"><p><b>Required</b>.  The name of the property
210 which contains the Array of row objects.  Defaults to <tt>undefined</tt>.
211 An exception will be thrown if the root property is undefined. The data
212 packet value for this property should be an empty array to clear the data
213 or show no data.</p>
214 </div></div></div><div id="config-successProperty" class="member inherited"><a href="Ext.data.reader.Json.html#config-successProperty" rel="config-successProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-successProperty" class="viewSource">view source</a></div><a name="successProperty"></a><a name="config-successProperty"></a><a href="Ext.data.reader.Json.html#" rel="config-successProperty" class="cls expand">successProperty</a><span> : String</span></div><div class="description"><div class="short">Name of the property from which to
215 retrieve the success attribute. Defaults to success.  See
216 Ext.data.proxy.Proxy.exc...</div><div class="long"><p>Name of the property from which to
217 retrieve the success attribute. Defaults to <tt>success</tt>.  See
218 <a href="Ext.data.proxy.Proxy.html" rel="Ext.data.proxy.Proxy" class="docClass">Ext.data.proxy.Proxy</a>.<a href="Ext.data.proxy.Proxy.html#exception" rel="Ext.data.proxy.Proxy#exception" class="docClass">exception</a>
219 for additional information.</p>
220 </div></div></div><div id="config-totalProperty" class="member inherited"><a href="Ext.data.reader.Json.html#config-totalProperty" rel="config-totalProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-totalProperty" class="viewSource">view source</a></div><a name="totalProperty"></a><a name="config-totalProperty"></a><a href="Ext.data.reader.Json.html#" rel="config-totalProperty" class="cls expand">totalProperty</a><span> : String</span></div><div class="description"><div class="short">Name of the property from which to
221 retrieve the total number of records in the dataset. This is only needed
222 if the wh...</div><div class="long"><p>Name of the property from which to
223 retrieve the total number of records in the dataset. This is only needed
224 if the whole dataset is not passed in one go, but is being paged from
225 the remote server.  Defaults to <tt>total</tt>.</p>
226 </div></div></div><div id="config-useSimpleAccessors" class="member ni"><a href="Ext.data.reader.Json.html#config-useSimpleAccessors" rel="config-useSimpleAccessors" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Json.html" class="definedIn docClass">Ext.data.reader.Json</a><br/><a href="../source/Json.html#Ext-data.reader.Json-cfg-useSimpleAccessors" class="viewSource">view source</a></div><a name="useSimpleAccessors"></a><a name="config-useSimpleAccessors"></a><a href="Ext.data.reader.Json.html#" rel="config-useSimpleAccessors" class="cls expand">useSimpleAccessors</a><span> : Boolean</span></div><div class="description"><div class="short">True to ensure that field names/mappings are treated as literals when
227 reading values. Defalts to false.
228 For example, ...</div><div class="long"><p>True to ensure that field names/mappings are treated as literals when
229 reading values. Defalts to <tt>false</tt>.
230 For example, by default, using the mapping "foo.bar.baz" will try and read a property foo from the root, then a property bar
231 from foo, then a property baz from bar. Setting the simple accessors to true will read the property with the name
232 "foo.bar.baz" direct from the root object.</p>
233 </div></div></div></div><div class="m-properties"><a name="properties"></a><div class="definedBy">Defined By</div><h3 class="prp p">Properties</h3><div id="property-jsonData" class="member f ni"><a href="Ext.data.reader.Json.html#property-jsonData" rel="property-jsonData" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Json.html" class="definedIn docClass">Ext.data.reader.Json</a><br/><a href="../source/Json.html#Ext-data.reader.Json-property-jsonData" class="viewSource">view source</a></div><a name="jsonData"></a><a name="property-jsonData"></a><a href="Ext.data.reader.Json.html#" rel="property-jsonData" class="cls expand">jsonData</a><span> : Mixed</span></div><div class="description"><div class="short"><p>DEPRECATED - will be removed in <a href="Ext.html" rel="Ext" class="docClass">Ext</a> JS 5.0. This is just a copy of this.rawData - use that instead</p>
234 </div><div class="long"><p>DEPRECATED - will be removed in <a href="Ext.html" rel="Ext" class="docClass">Ext</a> JS 5.0. This is just a copy of this.rawData - use that instead</p>
235 </div></div></div><div id="property-rawData" class="member inherited"><a href="Ext.data.reader.Json.html#property-rawData" rel="property-rawData" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-property-rawData" class="viewSource">view source</a></div><a name="rawData"></a><a name="property-rawData"></a><a href="Ext.data.reader.Json.html#" rel="property-rawData" class="cls expand">rawData</a><span> : Mixed</span></div><div class="description"><div class="short"><p>The raw data object that was last passed to readRecords. Stored for further processing if needed</p>
236 </div><div class="long"><p>The raw data object that was last passed to readRecords. Stored for further processing if needed</p>
237 </div></div></div></div><div class="m-methods"><a name="methods"></a><div class="definedBy">Defined By</div><h3 class="mth p">Methods</h3><div id="method-Json" class="member f inherited"><a href="Ext.data.reader.Json.html#method-Json" rel="method-Json" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-constructor" class="viewSource">view source</a></div><a name="Json"></a><a name="method-Json"></a><a href="Ext.data.reader.Json.html#" rel="method-Json" class="cls expand">Json</a>(
238 <span class="pre">Object config</span>)
239  : void</div><div class="description"><div class="short"><p>&nbsp;</p></div><div class="long">
240 <h3 class="pa">Parameters</h3><ul><li><span class="pre">config</span> : Object<div class="sub-desc"><p>Optional config object</p>
241 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
242 </li></ul></div></div></div><div id="method-getResponseData" class="member inherited"><a href="Ext.data.reader.Json.html#method-getResponseData" rel="method-getResponseData" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-getResponseData" class="viewSource">view source</a></div><a name="getResponseData"></a><a name="method-getResponseData"></a><a href="Ext.data.reader.Json.html#" rel="method-getResponseData" class="cls expand">getResponseData</a>(
243 <span class="pre">Object response</span>)
244  : Object</div><div class="description"><div class="short">Takes a raw response object (as passed to this.read) and returns the useful data segment of it. This must be implemen...</div><div class="long"><p>Takes a raw response object (as passed to this.read) and returns the useful data segment of it. This must be implemented by each subclass</p>
245 <h3 class="pa">Parameters</h3><ul><li><span class="pre">response</span> : Object<div class="sub-desc"><p>The responce object</p>
246 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Object</span>&nbsp; &nbsp;<p>The useful data from the response</p>
247 </li></ul></div></div></div><div id="method-read" class="member inherited"><a href="Ext.data.reader.Json.html#method-read" rel="method-read" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-read" class="viewSource">view source</a></div><a name="read"></a><a name="method-read"></a><a href="Ext.data.reader.Json.html#" rel="method-read" class="cls expand">read</a>(
248 <span class="pre">Object response</span>)
249  : Ext.data.ResultSet</div><div class="description"><div class="short">Reads the given response object. This method normalizes the different types of response object that may be passed
250 to ...</div><div class="long"><p>Reads the given response object. This method normalizes the different types of response object that may be passed
251 to it, before handing off the reading of records to the <a href="Ext.data.reader.Json.html#readRecords" rel="Ext.data.reader.Json#readRecords" class="docClass">readRecords</a> function.</p>
252 <h3 class="pa">Parameters</h3><ul><li><span class="pre">response</span> : Object<div class="sub-desc"><p>The response object. This may be either an XMLHttpRequest object or a plain JS object</p>
253 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Ext.data.ResultSet</span>&nbsp; &nbsp;<p>The parsed ResultSet object</p>
254 </li></ul></div></div></div><div id="method-readRecords" class="member ni"><a href="Ext.data.reader.Json.html#method-readRecords" rel="method-readRecords" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Json.html" class="definedIn docClass">Ext.data.reader.Json</a><br/><a href="../source/Json.html#Ext-data.reader.Json-method-readRecords" class="viewSource">view source</a></div><a name="readRecords"></a><a name="method-readRecords"></a><a href="Ext.data.reader.Json.html#" rel="method-readRecords" class="cls expand">readRecords</a>(
255 <span class="pre">Object data</span>)
256  : Ext.data.ResultSet</div><div class="description"><div class="short">Reads a JSON object and returns a ResultSet. Uses the internal getTotal and getSuccess extractors to
257 retrieve meta da...</div><div class="long"><p>Reads a JSON object and returns a ResultSet. Uses the internal getTotal and getSuccess extractors to
258 retrieve meta data from the response, and extractData to turn the JSON data into model instances.</p>
259 <h3 class="pa">Parameters</h3><ul><li><span class="pre">data</span> : Object<div class="sub-desc"><p>The raw JSON data</p>
260 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Ext.data.ResultSet</span>&nbsp; &nbsp;<p>A ResultSet containing model instances and meta data about the results</p>
261 </li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>