/**
* 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 = Ext.create('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 #cfg-rootProperty} 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 #rootProperty} configuration that matches the 'users'
* above:
*
* reader: {
* type: 'json',
* rootProperty: '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',
* rootProperty: 'users',
* record: 'user'
* }
*
* ## Response MetaData
*
* The server can return metadata in its response, in addition to the record data, that describe
* attributes of the data set itself or are used to reconfigure the Reader. To pass metadata
* in the response you simply add a `metaData` attribute to the root of the response data.
* The metaData attribute can contain anything, but supports a specific set of properties
* that are handled by the Reader if they are present:
*
* - {@link #rootProperty}: the property name of the root response node containing the record data
* - {@link #totalProperty}: property name for the total number of records in the data
* - {@link #successProperty}: property name for the success status of the response
* - {@link #messageProperty}: property name for an optional response message
* - {@link Ext.data.Model#cfg-fields fields}: Config used to reconfigure the Model's fields
* before converting the response data into records
*
* An initial Reader configuration containing all of these properties might look like this
* ("fields" would be included in the Model definition, not shown):
*
* reader: {
* type: 'json',
* rootProperty: 'root',
* totalProperty: 'total',
* successProperty: 'success',
* messageProperty: 'message'
* }
*
* If you were to pass a response object containing attributes different from those initially
* defined above, you could use the `metaData` attribute to reconfigure the Reader on the fly.
* For example:
*
* {
* "count": 1,
* "ok": true,
* "msg": "Users found",
* "users": [{
* "userId": 123,
* "name": "Ed Spencer",
* "email": "ed@sencha.com"
* }],
* "metaData": {
* "rootProperty": "users",
* "totalProperty": 'count',
* "successProperty": 'ok',
* "messageProperty": 'msg'
* }
* }
*
* You can also place any other arbitrary data you need into the `metaData` attribute which will be
* ignored by the Reader, but will be accessible via the Reader's {@link #metaData} property
* (which is also passed to listeners via the Proxy's
* {@link Ext.data.proxy.Proxy#metachange metachange} event (also relayed by the store).
* Application code can then process the passed metadata in any way it chooses.
*
* A simple example for how this can be used would be customizing the fields for a Model that is
* bound to a grid. By passing the `fields` property the Model will be automatically updated by the
* Reader internally, but that change will not be reflected automatically in the grid unless you
* also update the column configuration. You could do this manually, or you could simply pass
* a standard grid {@link Ext.panel.Table#columns column} config object as part of the `metaData`
* attribute and then pass that along to the grid. Here's a very simple example for how that
* could be accomplished:
*
* // response format:
* {
* ...
* "metaData": {
* "fields": [
* { "name": "userId", "type": "int" },
* { "name": "name", "type": "string" },
* { "name": "birthday", "type": "date", "dateFormat": "Y-j-m" },
* ],
* "columns": [
* { "text": "User ID", "dataIndex": "userId", "width": 40 },
* { "text": "User Name", "dataIndex": "name", "flex": 1 },
* { "text": "Birthday", "dataIndex": "birthday", "flex": 1,
* "format": 'Y-j-m', "xtype": "datecolumn" }
* ]
* }
* }
*
* The Reader will automatically read the meta fields config and rebuild the Model based on the new
* fields, but to handle the new column configuration you would need to handle the metadata within
* the application code. This is done simply enough by handling the metachange event on either
* the store or the proxy, e.g.:
*
* var store = Ext.create('Ext.data.Store', {
* ...
* listeners: {
* 'metachange': function(store, meta) {
* myGrid.reconfigure(store, meta.columns);
* }
* }
* });
*
*/
Ext.define('Ext.data.reader.Json', {
extend: 'Ext.data.reader.Reader',
alternateClassName: 'Ext.data.JsonReader',
alias: 'reader.json',
requires: [
'Ext.JSON'
],
config: {
/**
* @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.
*/
record: null,
/**
* @cfg {String} [metaProperty]
* Name of the property from which to retrieve the `metaData` attribute. See
* {@link #metaData}.
*/
metaProperty: 'metaData',
/**
* @cfg {Boolean} useSimpleAccessors True to ensure that field names/mappings are treated
* as literals when reading values.
*
* 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,
/**
* @cfg {Boolean} preserveRawData
* The reader will keep a copy of the most recent request in the {@link #rawData} property.
* For performance reasons, the data object for each record is used directly as the model
* data. This means that these objects may be modified and thus modify the raw data.
* To ensure the objects are copied, set this option to `true`.
* NB: This only applies to items that are read as part of the data array, any other
* metadata will not be modified:
*
* {
* "someOtherData": 1, // Won't be modified
* "root": [{}, {}, {}] // The objects here will be modified
* }
*/
preserveRawData: false
},
/**
* @private
*/
responseType: 'json',
updateRootProperty: function() {
this.forceBuildExtractors();
},
updateMetaProperty: function() {
this.forceBuildExtractors();
},
/**
* @method readRecords
* 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
* @param {Object} [readOptions] See {@link #read} for details.
* @return {Ext.data.ResultSet} A ResultSet containing model instances and meta data about
* the results
*/
getResponseData: function(response) {
var error;
if (typeof response.responseJson === 'object') {
return response.responseJson;
}
try {
return Ext.decode(response.responseText);
}
catch (ex) {
error = this.createReadError(ex.message);
Ext.Logger.warn('Unable to parse the JSON returned by the server');
this.fireEvent('exception', this, response, error);
return error;
}
},
buildExtractors: function(force) {
var me = this,
emptyFn = Ext.emptyFn;
// Will only return true if we need to build
if (me.callParent([force])) {
me.getRoot = me.setupExtractor(me.getRootProperty(), Ext.identityFn);
me.getGroupRoot = me.setupExtractor(me.getGroupRootProperty(), emptyFn);
me.getSummaryRoot = me.setupExtractor(me.getSummaryRootProperty(), emptyFn);
me.getMeta = me.setupExtractor(me.getMetaProperty(), emptyFn);
}
},
/**
* @private
* We're just preparing the data for the superclass by pulling out the record objects we want.
* If a {@link #record} was specified we have to pull those out of the larger JSON object,
* which is most of what this function is doing
* @param {Object} root The JSON root node
* @param {Object} [readOptions] See {@link #read} for details.
* @return {Ext.data.Model[]} The records
*/
extractData: function(root, readOptions) {
var recordName = this.getRecord(),
data = [],
length, i;
if (recordName) {
length = root.length;
if (!length && Ext.isObject(root)) {
length = 1;
root = [root];
}
for (i = 0; i < length; i++) {
data[i] = root[i][recordName];
}
}
else {
data = root;
}
return this.callParent([data, readOptions]);
},
getModelData: function(raw) {
return this.getPreserveRawData() ? Ext.apply({}, raw) : raw;
},
/**
* @private
* @method
* Returns an accessor function for the given property string. Gives support for properties
* such as the following:
*
* - 'someProperty'
* - 'some.property'
* - '["someProperty"]'
* - 'values[0]'
*
* This is used by {@link #buildExtractors} to create optimized extractor functions for
* properties that are looked up directly on the source object (e.g. {@link #successProperty},
* {@link #messageProperty}, etc.).
*/
createAccessor: (function() {
var re = /[\[\.]/; // eslint-disable-line no-useless-escape
return function(expr) {
var simple = this.getUseSimpleAccessors(),
operatorIndex, result,
current, parts, part, inExpr,
isDot, isLeft, isRight,
special, c, i, bracketed, len;
if (!(expr || expr === 0)) {
return;
}
if (typeof expr === 'function') {
return expr;
}
if (!simple) {
operatorIndex = String(expr).search(re);
}
if (simple === true || operatorIndex < 0) {
result = function(raw) {
return raw == null ? null : raw[expr];
};
}
else {
// The purpose of this part is to generate a "safe" accessor for any complex
// json expression. For example 'foo.bar.baz' will get transformed:
// raw.foo && raw.foo.bar && raw.foo.bar.baz
current = 'raw';
parts = [];
part = '';
inExpr = 0;
len = expr.length;
// The <= is intentional here. We handle the last character
// being undefined so that we can append any final values at
// the end
for (i = 0; i <= len; ++i) {
c = expr[i];
isDot = c === '.';
isLeft = c === '[';
isRight = c === ']';
special = isDot || isLeft || isRight || !c;
// If either:
// a) Not a special char
// b) We're nested more than 1 deep, no single char can bring us out
// c) We are in an expr & it's not an ending brace
// Then just push the character on
if (!special || inExpr > 1 || (inExpr && !isRight)) {
part += c;
}
else if (special) {
bracketed = false;
if (isLeft) {
++inExpr;
}
else if (isRight) {
--inExpr;
bracketed = true;
}
if (part) {
if (bracketed) {
part = '[' + part + ']';
}
else {
part = '.' + part;
}
current += part;
// Concatting the empty string to the start fixes a very odd
// intermittent bug with IE9/10.
// On some occasions, without it, it will end up generating
// raw.foo.bar.baz && raw.foo.bar.baz && raw.foo.bar.baz
// At this point, not really sure why forcibly casting it to a string
// makes a difference
parts.push('' + current);
part = '';
}
}
}
result = parts.join(' && ');
result = Ext.functionFactory('raw', 'return ' + result);
}
return result;
};
}()),
/**
* @private
* @method
* Returns an accessor function for the passed Field. Gives support for properties such as
* the following:
*
* - 'someProperty'
* - 'some.property'
* - '["someProperty"]'
* - 'values[0]'
*
* This is used by {@link #buildExtractors} to create optimized extractor expressions when
* converting raw data into model instances. This method is used at the field level to
* dynamically map values to model fields.
*/
createFieldAccessor: function(field) {
// Need to capture me for the extractor
var me = this,
mapping = field.mapping,
hasMap = mapping || mapping === 0,
map = hasMap ? mapping : field.name;
if (hasMap) {
if (typeof map === 'function') {
return function(raw, self) {
return field.mapping(raw, self);
};
}
else {
return me.createAccessor(map);
}
}
},
getAccessorKey: function(prop) {
var simple = this.getUseSimpleAccessors() ? 'simple' : '';
return this.callParent([simple + prop]);
},
privates: {
copyFrom: function(reader) {
this.callParent([reader]);
this.getRoot = reader.getRoot;
},
getGroupRoot: function(data) {
this.buildExtractors();
return this.getGroupRoot(data);
},
getSummaryRoot: function(data) {
this.buildExtractors();
return this.getSummaryRoot(data);
},
setupExtractor: function(prop, defaultFn) {
return prop ? this.getAccessor(prop) : defaultFn;
}
}
});