The JSON Reader is used by a Proxy to read a server response that is sent back in JSON format. This usually + * happens as a result of loading a Store - for example we might create something like this:
+ * +
+Ext.define('User', {
+ extend: 'Ext.data.Model',
+ fields: ['id', 'name', 'email']
+});
+
+var store = new Ext.data.Store({
+ model: 'User',
+ proxy: {
+ type: 'ajax',
+ url : 'users.json',
+ reader: {
+ type: 'json'
+ }
+ }
+});
+The example above creates a 'User' model. Models are explained in the {@link Ext.data.Model Model} docs if you're + * not already familiar with them.
+ * + *We created the simplest type of JSON Reader possible by simply telling our {@link Ext.data.Store Store}'s + * {@link Ext.data.proxy.Proxy Proxy} that we want a JSON Reader. The Store automatically passes the configured model to the + * Store, so it is as if we passed this instead: + * +
+reader: {
+ type : 'json',
+ model: 'User'
+}
+The reader we set up is ready to read data from our server - at the moment it will accept a response like this:
+ * +
+[
+ {
+ "id": 1,
+ "name": "Ed Spencer",
+ "email": "ed@sencha.com"
+ },
+ {
+ "id": 2,
+ "name": "Abe Elias",
+ "email": "abe@sencha.com"
+ }
+]
+Reading other JSON formats
+ * + *If you already have your JSON format defined and it doesn't look quite like what we have above, you can usually + * pass JsonReader a couple of configuration options to make it parse your format. For example, we can use the + * {@link #root} configuration to parse data that comes back like this:
+ * +
+{
+ "users": [
+ {
+ "id": 1,
+ "name": "Ed Spencer",
+ "email": "ed@sencha.com"
+ },
+ {
+ "id": 2,
+ "name": "Abe Elias",
+ "email": "abe@sencha.com"
+ }
+ ]
+}
+To parse this we just pass in a {@link #root} configuration that matches the 'users' above:
+ * +
+reader: {
+ type: 'json',
+ root: 'users'
+}
+Sometimes the JSON structure is even more complicated. Document databases like CouchDB often provide metadata + * around each record inside a nested structure like this:
+ * +
+{
+ "total": 122,
+ "offset": 0,
+ "users": [
+ {
+ "id": "ed-spencer-1",
+ "value": 1,
+ "user": {
+ "id": 1,
+ "name": "Ed Spencer",
+ "email": "ed@sencha.com"
+ }
+ }
+ ]
+}
+In the case above the record data is nested an additional level inside the "users" array as each "user" item has + * additional metadata surrounding it ('id' and 'value' in this case). To parse data out of each "user" item in the + * JSON above we need to specify the {@link #record} configuration like this:
+ * +
+reader: {
+ type : 'json',
+ root : 'users',
+ record: 'user'
+}
+Response metadata
+ * + *The server can return additional data in its response, such as the {@link #totalProperty total number of records} + * and the {@link #successProperty success status of the response}. These are typically included in the JSON response + * like this:
+ * +
+{
+ "total": 100,
+ "success": true,
+ "users": [
+ {
+ "id": 1,
+ "name": "Ed Spencer",
+ "email": "ed@sencha.com"
+ }
+ ]
+}
+If these properties are present in the JSON response they can be parsed out by the JsonReader and used by the + * Store that loaded it. We can set up the names of these properties by specifying a final pair of configuration + * options:
+ * +
+reader: {
+ type : 'json',
+ root : 'users',
+ totalProperty : 'total',
+ successProperty: 'success'
+}
+These final options are not necessary to make the Reader work, but can be useful when the server needs to report + * an error or if it needs to indicate that there is a lot of data available of which only a subset is currently being + * returned.
+ */ +Ext.define('Ext.data.reader.Json', { + extend: 'Ext.data.reader.Reader', + alternateClassName: 'Ext.data.JsonReader', + alias : 'reader.json', + + root: '', + + /** + * @cfg {String} record The optional location within the JSON response that the record data itself can be found at. + * See the JsonReader intro docs for more details. This is not often needed and defaults to undefined. + */ + + /** + * @cfg {Boolean} useSimpleAccessors True to ensure that field names/mappings are treated as literals when + * reading values. Defalts to false. + * For example, by default, using the mapping "foo.bar.baz" will try and read a property foo from the root, then a property bar + * from foo, then a property baz from bar. Setting the simple accessors to true will read the property with the name + * "foo.bar.baz" direct from the root object. + */ + useSimpleAccessors: false, + + /** + * Reads a JSON object and returns a ResultSet. Uses the internal getTotal and getSuccess extractors to + * retrieve meta data from the response, and extractData to turn the JSON data into model instances. + * @param {Object} data The raw JSON data + * @return {Ext.data.ResultSet} A ResultSet containing model instances and meta data about the results + */ + readRecords: function(data) { + //this has to be before the call to super because we use the meta data in the superclass readRecords + if (data.metaData) { + this.onMetaChange(data.metaData); + } + + /** + * DEPRECATED - will be removed in Ext JS 5.0. This is just a copy of this.rawData - use that instead + * @property jsonData + * @type Mixed + */ + this.jsonData = data; + return this.callParent([data]); + }, + + //inherit docs + getResponseData: function(response) { + try { + var data = Ext.decode(response.responseText); + } + catch (ex) { + Ext.Error.raise({ + response: response, + json: response.responseText, + parseError: ex, + msg: 'Unable to parse the JSON returned by the server: ' + ex.toString() + }); + } + //