/**
* @author Ed Spencer
* @class Ext.data.reader.Reader
* @extends Object
*
* <p>Readers are used to interpret data to be loaded into a {@link Ext.data.Model Model} instance or a {@link Ext.data.Store Store}
* - usually in response to an AJAX request. This is normally handled transparently by passing some configuration to either the
* {@link Ext.data.Model Model} or the {@link Ext.data.Store Store} in question - see their documentation for further details.</p>
*
* <p><u>Loading Nested Data</u></p>
*
* <p>Readers have the ability to automatically load deeply-nested data objects based on the {@link Ext.data.Association associations}
* configured on each Model. Below is an example demonstrating the flexibility of these associations in a fictional CRM system which
* manages a User, their Orders, OrderItems and Products. First we'll define the models:
*
<pre><code>
Ext.define("User", {
extend: 'Ext.data.Model',
fields: [
'id', 'name'
],
hasMany: {model: 'Order', name: 'orders'},
proxy: {
type: 'rest',
url : 'users.json',
reader: {
type: 'json',
root: 'users'
}
}
});
Ext.define("Order", {
extend: 'Ext.data.Model',
fields: [
'id', 'total'
],
hasMany : {model: 'OrderItem', name: 'orderItems', associationKey: 'order_items'},
belongsTo: 'User'
});
Ext.define("OrderItem", {
extend: 'Ext.data.Model',
fields: [
'id', 'price', 'quantity', 'order_id', 'product_id'
],
belongsTo: ['Order', {model: 'Product', associationKey: 'product'}]
});
Ext.define("Product", {
extend: 'Ext.data.Model',
fields: [
'id', 'name'
],
hasMany: 'OrderItem'
});
</code></pre>
*
* <p>This may be a lot to take in - basically a User has many Orders, each of which is composed of several OrderItems. Finally,
* each OrderItem has a single Product. This allows us to consume data like this:</p>
*
<pre><code>
{
"users": [
{
"id": 123,
"name": "Ed",
"orders": [
{
"id": 50,
"total": 100,
"order_items": [
{
"id" : 20,
"price" : 40,
"quantity": 2,
"product" : {
"id": 1000,
"name": "MacBook Pro"
}
},
{
"id" : 21,
"price" : 20,
"quantity": 3,
"product" : {
"id": 1001,
"name": "iPhone"
}
}
]
}
]
}
]
}
</code></pre>
*
* <p>The JSON response is deeply nested - it returns all Users (in this case just 1 for simplicity's sake), all of the Orders
* for each User (again just 1 in this case), all of the OrderItems for each Order (2 order items in this case), and finally
* the Product associated with each OrderItem. Now we can read the data and use it as follows:
*
<pre><code>
var store = new Ext.data.Store({
model: "User"
});
store.load({
callback: function() {
//the user that was loaded
var user = store.first();
console.log("Orders for " + user.get('name') + ":")
//iterate over the Orders for each User
user.orders().each(function(order) {
console.log("Order ID: " + order.getId() + ", which contains items:");
//iterate over the OrderItems for each Order
order.orderItems().each(function(orderItem) {
//we know that the Product data is already loaded, so we can use the synchronous getProduct
//usually, we would use the asynchronous version (see {@link Ext.data.BelongsToAssociation})
var product = orderItem.getProduct();
console.log(orderItem.get('quantity') + ' orders of ' + product.get('name'));
});
});
}
});
</code></pre>
*
* <p>Running the code above results in the following:</p>
*
<pre><code>
Orders for Ed:
Order ID: 50, which contains items:
2 orders of MacBook Pro
3 orders of iPhone
</code></pre>
*
* @constructor
* @param {Object} config Optional config object
*/
Ext.define('Ext.data.reader.Reader', {
requires: ['Ext.data.ResultSet'],
alternateClassName: ['Ext.data.Reader', 'Ext.data.DataReader'],
/**
* @cfg {String} idProperty Name of the property within a row object
* that contains a record identifier value. Defaults to <tt>The id of the model</tt>.
* If an idProperty is explicitly specified it will override that of the one specified
* on the model
*/
/**
* @cfg {String} totalProperty Name of the property from which to
* retrieve the total number of records in the dataset. This is only needed
* if the whole dataset is not passed in one go, but is being paged from
* the remote server. Defaults to <tt>total</tt>.
*/
totalProperty: 'total',
/**
* @cfg {String} successProperty Name of the property from which to
* retrieve the success attribute. Defaults to <tt>success</tt>. See
* {@link Ext.data.proxy.Proxy}.{@link Ext.data.proxy.Proxy#exception exception}
* for additional information.
*/
successProperty: 'success',
/**
* @cfg {String} root <b>Required</b>. The name of the property
* which contains the Array of row objects. Defaults to <tt>undefined</tt>.
* An exception will be thrown if the root property is undefined. The data
* packet value for this property should be an empty array to clear the data
* or show no data.
*/
root: '',
/**
* @cfg {String} messageProperty The name of the property which contains a response message.
* This property is optional.
*/
/**
* @cfg {Boolean} implicitIncludes True to automatically parse models nested within other models in a response
* object. See the Ext.data.reader.Reader intro docs for full explanation. Defaults to true.
*/
implicitIncludes: true,
isReader: true,
constructor: function(config) {
var me = this;
Ext.apply(me, config || {});
me.fieldCount = 0;
me.model = Ext.ModelManager.getModel(config.model);
if (me.model) {
me.buildExtractors();
}
},
/**
* Sets a new model for the reader.
* @private
* @param {Object} model The model to set.
* @param {Boolean} setOnProxy True to also set on the Proxy, if one is configured
*/
setModel: function(model, setOnProxy) {
var me = this;
me.model = Ext.ModelManager.getModel(model);
me.buildExtractors(true);
if (setOnProxy && me.proxy) {
me.proxy.setModel(me.model, true);
}
},
/**
* Reads the given response object. This method normalizes the different types of response object that may be passed
* to it, before handing off the reading of records to the {@link #readRecords} function.
* @param {Object} response The response object. This may be either an XMLHttpRequest object or a plain JS object
* @return {Ext.data.ResultSet} The parsed ResultSet object
*/
read: function(response) {
var data = response;
if (response && response.responseText) {
data = this.getResponseData(response);
}
if (data) {
return this.readRecords(data);
} else {
return this.nullResultSet;
}
},
/**
* Abstracts common functionality used by all Reader subclasses. Each subclass is expected to call
* this function before running its own logic and returning the Ext.data.ResultSet instance. For most
* Readers additional processing should not be needed.
* @param {Mixed} data The raw data object
* @return {Ext.data.ResultSet} A ResultSet object
*/
readRecords: function(data) {
var me = this;
/*
* We check here whether the number of fields has changed since the last read.
* This works around an issue when a Model is used for both a Tree and another
* source, because the tree decorates the model with extra fields and it causes
* issues because the readers aren't notified.
*/
if (me.fieldCount !== me.getFields().length) {
me.buildExtractors(true);
}
/**
* The raw data object that was last passed to readRecords. Stored for further processing if needed
* @property rawData
* @type Mixed
*/
me.rawData = data;
data = me.getData(data);
// If we pass an array as the data, we dont use getRoot on the data.
// Instead the root equals to the data.
var root = Ext.isArray(data) ? data : me.getRoot(data),
success = true,
recordCount = 0,
total, value, records, message;
if (root) {
total = root.length;
}
if (me.totalProperty) {
value = parseInt(me.getTotal(data), 10);
if (!isNaN(value)) {
total = value;
}
}
if (me.successProperty) {
value = me.getSuccess(data);
if (value === false || value === 'false') {
success = false;
}
}
if (me.messageProperty) {
message = me.getMessage(data);
}
if (root) {
records = me.extractData(root);
recordCount = records.length;
} else {
recordCount = 0;
records = [];
}
return Ext.create('Ext.data.ResultSet', {
total : total || recordCount,
count : recordCount,
records: records,
success: success,
message: message
});
},
* Returns extracted, type-cast rows of data. Iterates to call #extractValues for each row
* @param {Object[]/Object} data-root from server response
* @private
*/
extractData : function(root) {
var me = this,
values = [],
records = [],
Model = me.model,
i = 0,
length = root.length,
idProp = me.getIdProperty(),
node, id, record;
if (!root.length && Ext.isObject(root)) {
root = [root];
length = 1;
}
for (; i < length; i++) {
node = root[i];
values = me.extractValues(node);
id = me.getId(node);
record = new Model(values, id, node);
records.push(record);
if (me.implicitIncludes) {
me.readAssociated(record, node);
}
}
return records;
},
/**
* @private
* Loads a record's associations from the data object. This prepopulates hasMany and belongsTo associations
* on the record provided.
* @param {Ext.data.Model} record The record to load associations for
* @param {Mixed} data The data object
* @return {String} Return value description
*/
readAssociated: function(record, data) {
var associations = record.associations.items,
i = 0,
length = associations.length,
association, associationData, proxy, reader;
for (; i < length; i++) {
association = associations[i];
associationData = this.getAssociatedDataRoot(data, association.associationKey || association.name);
if (associationData) {
reader = association.getReader();
if (!reader) {
proxy = association.associatedModel.proxy;
// if the associated model has a Reader already, use that, otherwise attempt to create a sensible one
if (proxy) {
reader = proxy.getReader();
} else {
reader = new this.constructor({
model: association.associatedName
});
}
}
association.read(record, reader, associationData);
}
}
},
/**
* @private
* Used internally by {@link #readAssociated}. Given a data object (which could be json, xml etc) for a specific
* record, this should return the relevant part of that data for the given association name. This is only really
* needed to support the XML Reader, which has to do a query to get the associated data object
* @param {Mixed} data The raw data object
* @param {String} associationName The name of the association to get data for (uses associationKey if present)
* @return {Mixed} The root
*/
getAssociatedDataRoot: function(data, associationName) {
return data[associationName];
},
getFields: function() {
return this.model.prototype.fields.items;
},
* @private
* Given an object representing a single model instance's data, iterates over the model's fields and
* builds an object with the value for each field.
* @param {Object} data The data object to convert
* @return {Object} Data object suitable for use with a model constructor
*/
extractValues: function(data) {
var fields = this.getFields(),
i = 0,
length = fields.length,
output = {},
field, value;
for (; i < length; i++) {
field = fields[i];
value = this.extractorFunctions[i](data);
output[field.name] = value;
}
return output;
},
/**
* @private
* By default this function just returns what is passed to it. It can be overridden in a subclass
* to return something else. See XmlReader for an example.
* @param {Object} data The data object
* @return {Object} The normalized data object
*/
getData: function(data) {
return data;
},
/**
* @private
* This will usually need to be implemented in a subclass. Given a generic data object (the type depends on the type
* of data we are reading), this function should return the object as configured by the Reader's 'root' meta data config.
* See XmlReader's getRoot implementation for an example. By default the same data object will simply be returned.
* @param {Mixed} data The data object
* @return {Mixed} The same data object
*/
getRoot: function(data) {
return data;
},
/**
* 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
* @param {Object} response The responce object
* @return {Object} The useful data from the response
*/
getResponseData: function(response) {
//<debug>
Ext.Error.raise("getResponseData must be implemented in the Ext.data.reader.Reader subclass");
//</debug>
},
/**
* @private
* Reconfigures the meta data tied to this Reader
*/
onMetaChange : function(meta) {
var fields = meta.fields,
newModel;
Ext.apply(this, meta);
if (fields) {
newModel = Ext.define("Ext.data.reader.Json-Model" + Ext.id(), {
extend: 'Ext.data.Model',
fields: fields
});
this.setModel(newModel, true);
} else {
this.buildExtractors(true);
}
},
/**
* Get the idProperty to use for extracting data
* @private
* @return {String} The id property
*/
getIdProperty: function(){
var prop = this.idProperty;
if (Ext.isEmpty(prop)) {
prop = this.model.prototype.idProperty;
}
return prop;
},
* @private
* This builds optimized functions for retrieving record data and meta data from an object.
* Subclasses may need to implement their own getRoot function.
* @param {Boolean} force True to automatically remove existing extractor functions first (defaults to false)
*/
buildExtractors: function(force) {
var me = this,
idProp = me.getIdProperty(),
totalProp = me.totalProperty,
successProp = me.successProperty,
messageProp = me.messageProperty,
accessor;
if (force === true) {
delete me.extractorFunctions;
}
if (me.extractorFunctions) {
return;
}
//build the extractors for all the meta data
if (totalProp) {
me.getTotal = me.createAccessor(totalProp);
}
if (successProp) {
me.getSuccess = me.createAccessor(successProp);
}
if (messageProp) {
me.getMessage = me.createAccessor(messageProp);
}
if (idProp) {
accessor = me.createAccessor(idProp);
me.getId = function(record) {
var id = accessor.call(me, record);
return (id === undefined || id === '') ? null : id;
};
} else {
me.getId = function() {
return null;
};
}
me.buildFieldExtractors();
},
* @private
*/
buildFieldExtractors: function() {
//now build the extractors for all the fields
var me = this,
fields = me.getFields(),
ln = fields.length,
i = 0,
extractorFunctions = [],
field, map;
for (; i < ln; i++) {
field = fields[i];
map = (field.mapping !== undefined && field.mapping !== null) ? field.mapping : field.name;
extractorFunctions.push(me.createAccessor(map));
}
me.fieldCount = ln;
me.extractorFunctions = extractorFunctions;
}
}, function() {
Ext.apply(this, {
// Private. Empty ResultSet to return when response is falsy (null|undefined|empty string)
nullResultSet: Ext.create('Ext.data.ResultSet', {
total : 0,
count : 0,
records: [],
success: true
})
});
});