/** * @author Ed Spencer * @class Ext.data.XmlReader * @extends Ext.data.Reader * * *The XML Reader is used by a Proxy to read a server response that is sent back in XML format. This usually * happens as a result of loading a Store - for example we might create something like this:
** *Ext.regModel('User', { fields: ['id', 'name', 'email'] }); var store = new Ext.data.Store({ model: 'User', proxy: { type: 'ajax', url : 'users.xml', reader: { type: 'xml', record: 'user' } } });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 XML Reader possible by simply telling our {@link Ext.data.Store Store}'s * {@link Ext.data.Proxy Proxy} that we want a XML Reader. The Store automatically passes the configured model to the * Store, so it is as if we passed this instead: *
* *reader: { type : 'xml', model: 'User', record: 'user' }The reader we set up is ready to read data from our server - at the moment it will accept a response like this:
** *<?xml version="1.0" encoding="UTF-8"?> <user> <id>1</id> <name>Ed Spencer</name> <email>[email protected]</email> </user> <user> <id>2</id> <name>Abe Elias</name> <email>[email protected]</email> </user>The XML Reader uses the configured {@link #record} option to pull out the data for each record - in this case we * set record to 'user', so each <user> above will be converted into a User model.
* *Reading other XML formats
* *If you already have your XML format defined and it doesn't look quite like what we have above, you can usually * pass XmlReader 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:
** *<?xml version="1.0" encoding="UTF-8"?> <users> <user> <id>1</id> <name>Ed Spencer</name> <email>[email protected]</email> </user> <user> <id>2</id> <name>Abe Elias</name> <email>[email protected]</email> </user> </users>To parse this we just pass in a {@link #root} configuration that matches the 'users' above:
** *reader: { type : 'xml', root : 'users', record: 'user' }Note that XmlReader doesn't care whether your {@link #root} and {@link #record} elements are nested deep inside * a larger structure, so a response like this will still work: *
* *<?xml version="1.0" encoding="UTF-8"?> <deeply> <nested> <xml> <users> <user> <id>1</id> <name>Ed Spencer</name> <email>[email protected]</email> </user> <user> <id>2</id> <name>Abe Elias</name> <email>[email protected]</email> </user> </users> </xml> </nested> </deeply>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 XML response * like this:
** *<?xml version="1.0" encoding="UTF-8"?> <total>100</total> <success>true</success> <users> <user> <id>1</id> <name>Ed Spencer</name> <email>[email protected]</email> </user> <user> <id>2</id> <name>Abe Elias</name> <email>[email protected]</email> </user> </users>If these properties are present in the XML response they can be parsed out by the XmlReader 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: 'xml', 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.
* *Response format
* *Note: in order for the browser to parse a returned XML document, the Content-Type header in the HTTP * response must be set to "text/xml" or "application/xml". This is very important - the XmlReader will not * work correctly otherwise.
*/ Ext.define('Ext.data.XmlReader', { extend: 'Ext.data.Reader', alias : 'reader.xml', /** * @private * Creates a function to return some particular key of data from a response. The totalProperty and * successProperty are treated as special cases for type casting, everything else is just a simple selector. * @param {String} key * @return {Function} */ /** * @cfg {String} record The DomQuery path to the repeated element which contains record information. * This is an alias for the {@link #root} config option. */ createAccessor: function() { var selectValue = function(expr, root){ var node = Ext.DomQuery.selectNode(expr, root), val; }; return function(expr) { var me = this; if (Ext.isEmpty(expr)) { return Ext.emptyFn; } if (Ext.isFunction(expr)) { return expr; } return function(root) { var node = Ext.DomQuery.selectNode(expr, root), val = me.getNodeValue(node); return Ext.isEmpty(val) ? null : val; }; }; }(), getNodeValue: function(node) { var val; if (node && node.firstChild) { val = node.firstChild.nodeValue; } return val || null; }, //inherit docs getResponseData: function(response) { var xml = response.responseXML; if (!xml) { throw {message: 'Ext.data.XmlReader.read: XML data not found'}; } return xml; }, /** * Normalizes the data object * @param {Object} data The raw data object * @return {Object} Returns the documentElement property of the data object if present, or the same object if not */ getData: function(data) { return data.documentElement || data; }, /** * @private * Given an XML object, returns the Element that represents the root as configured by the Reader's meta data * @param {Object} data The XML data object * @return {Element} The root node element */ getRoot: function(data) { var nodeName = data.nodeName, root = this.root; if (!root || (nodeName && nodeName == root)) { return data; } else { return Ext.DomQuery.selectNode(root, data); } }, //EVERYTHING BELOW THIS LINE WILL BE DEPRECATED IN EXT JS 5.0 /** * @cfg {String} idPath DEPRECATED - this will be removed in Ext JS 5.0. Please use idProperty instead */ /** * @cfg {String} id DEPRECATED - this will be removed in Ext JS 5.0. Please use idProperty instead */ /** * @cfg {String} success DEPRECATED - this will be removed in Ext JS 5.0. Please use successProperty instead */ /** * @constructor * @ignore * TODO: This can be removed in 5.0 as all it does is support some deprecated config */ constructor: function(config) { config = config || {}; // backwards compat, convert idPath or id / success // DEPRECATED - remove this in 5.0 Ext.applyIf(config, { idProperty : config.idPath || config.id || this.idProperty, successProperty: config.success || this.successProperty }); Ext.data.XmlReader.superclass.constructor.call(this, config); }, /** * @private * We're just preparing the data for the superclass by pulling out the record nodes we want * @param {Element} root The XML root node * @return {Array} The records */ extractData: function(root, returnRecords) { var recordName = this.record; if (recordName != root.nodeName) { root = Ext.DomQuery.select(recordName, root); } else { root = [root]; } return Ext.data.XmlReader.superclass.extractData.call(this, root, returnRecords); }, /** * @private * See Ext.data.Reader's getAssociatedDataRoot docs * @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 Ext.DomQuery.select(associationName, data)[0]; }, /** * Parses an XML document and returns a ResultSet containing the model instances * @param {Object} doc Parsed XML document * @return {Ext.data.ResultSet} The parsed result set */ readRecords: function(doc) { //it's possible that we get passed an array here by associations. Make sure we strip that out (see Ext.data.Reader#readAssociated) if (Ext.isArray(doc)) { doc = doc[0]; } /** * DEPRECATED - will be removed in Ext JS 5.0. This is just a copy of this.rawData - use that instead * @property xmlData * @type Object */ this.xmlData = doc; return Ext.data.XmlReader.superclass.readRecords.call(this, doc); } });