/** * 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.define('User', { * extend: 'Ext.data.Model', * fields: ['id', 'name', 'email'] * }); * * var store = Ext.create('Ext.data.Store', { * model: 'User', * proxy: { * type: 'ajax', * url: 'users.xml', * reader: { * type: 'xml', * record: 'user', * rootProperty: 'users' * } * } * }); * * 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 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', * rootProperty: 'users' * } * * 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"?> * <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> * * First off there's {@link #rootProperty} option to define the root node `<users>` (there should be * only one in a well-formed XML document). Then 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. * * Note that XmlReader doesn't care whether your {@link #rootProperty} 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> * * If this Reader is being used by a {@link Ext.data.TreeStore TreeStore} to read tree-structured * data in which records are nested as descendant nodes of other records, then this lenient * behaviour must be overridden by using a more specific child node selector as your {@link #record} * selector which will not select all descendants, such as: * * 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 XML response like this: * * <?xml version="1.0" encoding="UTF-8"?> * <users> * <total>100</total> * <success>true</success> * <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', * rootProperty: '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.reader.Xml', { extend: 'Ext.data.reader.Reader', alternateClassName: 'Ext.data.XmlReader', alias: 'reader.xml', requires: [ 'Ext.dom.Query' ], config: { /** * @cfg {String} record (required) * The DomQuery path to the repeated element which contains record information. * * By default, the elements which match the selector may be nested at any level * below the {@link #rootProperty} * * If this Reader is being used by a {@link Ext.data.TreeStore TreeStore} to read * tree-structured data, then only first generation child nodes of the root element must be * selected, so the record selector must be specified with a more specific selector which * will not select all descendants. For example: * * record: '>node' * */ record: '', /** * @cfg {String} namespace * A namespace prefix that will be prepended to the field name when reading a * field from an XML node. Take, for example, the following Model: * * Ext.define('Foo', { * extend: 'Ext.data.Model', * fields: ['bar', 'baz'] * }); * * The reader would need to be configured with a namespace of 'n' in order to read XML * data in the following format: * * <foo> * <n:bar>bar</n:bar> * <n:baz>baz</n:baz> * </foo> */ namespace: '' }, /** * @private */ responseType: 'document', /** * 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} expr * @return {Function} * @private */ createAccessor: function(expr) { if (Ext.isEmpty(expr)) { return Ext.emptyFn; } if (Ext.isFunction(expr)) { return expr; } return function(root) { return this.getNodeValue(Ext.DomQuery.selectNode(expr, root)); }; }, getNodeValue: function(node) { if (node) { // overcome a limitation of maximum textnode size // http://reference.sitepoint.com/javascript/Node/normalize // https://developer.mozilla.org/En/DOM/Node.normalize if (typeof node.normalize === 'function') { node.normalize(); } node = node.firstChild; if (node) { return node.nodeValue; } } return undefined; }, getResponseData: function(response) { var xml = response.responseXML, error = 'XML data not found in the response'; if (!xml) { Ext.Logger.warn(error); return this.createReadError(error); } return xml; }, /** * Normalizes the data object. * @param {Object} data The raw data object * @return {Object} 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 {XMLElement} The root node element */ getRoot: function(data) { return this.getRootValue(data, this.getRootProperty()); }, /** * @private * We're just preparing the data for the superclass by pulling out the record nodes we want. * @param {XMLElement} root The XML root node * @param {Object} [readOptions] See {@link #read} for details. * @return {Ext.data.Model[]} The records */ extractData: function(root, readOptions) { var recordName = this.getRecord(); //<debug> if (!recordName) { Ext.raise('Record is a required parameter'); } //</debug> if (recordName !== root.nodeName) { root = Ext.DomQuery.select(recordName, root); } else { root = [root]; } return this.callParent([root, readOptions]); }, /** * Parses an XML document and returns a ResultSet containing the model instances. * @param {Object} doc Parsed XML document * @param {Object} [readOptions] See {@link #read} for details. * @param {Object} [internalReadOptions] (private) * @return {Ext.data.ResultSet} The parsed result set */ readRecords: function(doc, readOptions, internalReadOptions) { // it's possible that we get passed an array here by associations. // Make sure we strip that out (see Ext.data.reader.Reader#readAssociated) if (Ext.isArray(doc)) { doc = doc[0]; } return this.callParent([doc, readOptions, internalReadOptions]); }, /** * @private * Returns an accessor function for the passed Field from an XML element using either the * Field's mapping, or its ordinal position in the fields collection as the index. * This is used by buildExtractors to create optimized on extractor function which converts * raw data into model instances. */ createFieldAccessor: function(field) { var namespace = this.getNamespace(), selector, autoMapping, result; if (field.mapping) { selector = field.mapping; } else { selector = (namespace ? namespace + '|' : '') + field.name; autoMapping = true; } if (typeof selector === 'function') { result = function(raw, self) { return field.mapping(raw, self); }; } else { // The generated field accessor is a *very* hot code path in XML reader, // so we try hard to optimize away any checks and lessen run time penalty. // We also try hard to use native code where possible, since Ext.DomQuery // is slow and very CPU intensive. // querySelector and getNodeValue break on namespaces so we can't use them if (autoMapping && !namespace && Ext.supports.XmlQuerySelector) { result = function(raw, self) { return self.getNodeValue(raw.querySelector(selector)); }; } if (!result) { result = function(raw, self) { return self.getNodeValue(Ext.DomQuery.selectNode(selector, raw)); }; } } return result; }, privates: { getGroupRoot: function(data) { return this.getRootValue(data, this.getGroupRootProperty()); }, getRootValue: function(data, prop) { var nodeName = data.nodeName; if (!prop || (nodeName && nodeName === prop)) { return data; } else if (typeof prop === 'function') { return prop(data); } else if (Ext.DomQuery.isXml(data)) { // This fix ensures we have XML data // Related to TreeStore calling getRoot with the root node, which isn't XML // Probably should be resolved in TreeStore at some point return Ext.DomQuery.selectNode(prop, data); } }, getSummaryRoot: function(data) { return this.getRootValue(data, this.getSummaryRootProperty()); } }, deprecated: { '5.1.1': { properties: { /** * @property {Object} xmlData * Copy of {@link #rawData}. * @deprecated 5.1.1 Removed in Ext JS 5.0. Use {@link #rawData} instead. */ xmlData: null } } }});