docs/source/Xml.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-data.reader.Xml'>/**
   2 </span> * @author Ed Spencer
   3  * @class Ext.data.reader.Xml
   4  * @extends Ext.data.reader.Reader
   5  *
   6  * &lt;p&gt;The XML Reader is used by a Proxy to read a server response that is sent back in XML format. This usually
   7  * happens as a result of loading a Store - for example we might create something like this:&lt;/p&gt;
   8  *
   9 &lt;pre&gt;&lt;code&gt;
  10 Ext.define('User', {
  11     extend: 'Ext.data.Model',
  12     fields: ['id', 'name', 'email']
  13 });
  14
  15 var store = new Ext.data.Store({
  16     model: 'User',
  17     proxy: {
  18         type: 'ajax',
  19         url : 'users.xml',
  20         reader: {
  21             type: 'xml',
  22             record: 'user'
  23         }
  24     }
  25 });
  26 &lt;/code&gt;&lt;/pre&gt;
  27  *
  28  * &lt;p&gt;The example above creates a 'User' model. Models are explained in the {@link Ext.data.Model Model} docs if you're
  29  * not already familiar with them.&lt;/p&gt;
  30  *
  31  * &lt;p&gt;We created the simplest type of XML Reader possible by simply telling our {@link Ext.data.Store Store}'s
  32  * {@link Ext.data.proxy.Proxy Proxy} that we want a XML Reader. The Store automatically passes the configured model to the
  33  * Store, so it is as if we passed this instead:
  34  *
  35 &lt;pre&gt;&lt;code&gt;
  36 reader: {
  37     type : 'xml',
  38     model: 'User',
  39     record: 'user'
  40 }
  41 &lt;/code&gt;&lt;/pre&gt;
  42  *
  43  * &lt;p&gt;The reader we set up is ready to read data from our server - at the moment it will accept a response like this:&lt;/p&gt;
  44  *
  45 &lt;pre&gt;&lt;code&gt;
  46 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
  47 &amp;lt;user&amp;gt;
  48     &amp;lt;id&amp;gt;1&amp;lt;/id&amp;gt;
  49     &amp;lt;name&amp;gt;Ed Spencer&amp;lt;/name&amp;gt;
  50     &amp;lt;email&amp;gt;ed@sencha.com&amp;lt;/email&amp;gt;
  51 &amp;lt;/user&amp;gt;
  52 &amp;lt;user&amp;gt;
  53     &amp;lt;id&amp;gt;2&amp;lt;/id&amp;gt;
  54     &amp;lt;name&amp;gt;Abe Elias&amp;lt;/name&amp;gt;
  55     &amp;lt;email&amp;gt;abe@sencha.com&amp;lt;/email&amp;gt;
  56 &amp;lt;/user&amp;gt;
  57 &lt;/code&gt;&lt;/pre&gt;
  58  *
  59  * &lt;p&gt;The XML Reader uses the configured {@link #record} option to pull out the data for each record - in this case we
  60  * set record to 'user', so each &amp;lt;user&amp;gt; above will be converted into a User model.&lt;/p&gt;
  61  *
  62  * &lt;p&gt;&lt;u&gt;Reading other XML formats&lt;/u&gt;&lt;/p&gt;
  63  *
  64  * &lt;p&gt;If you already have your XML format defined and it doesn't look quite like what we have above, you can usually
  65  * pass XmlReader a couple of configuration options to make it parse your format. For example, we can use the
  66  * {@link #root} configuration to parse data that comes back like this:&lt;/p&gt;
  67  *
  68 &lt;pre&gt;&lt;code&gt;
  69 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
  70 &amp;lt;users&amp;gt;
  71     &amp;lt;user&amp;gt;
  72         &amp;lt;id&amp;gt;1&amp;lt;/id&amp;gt;
  73         &amp;lt;name&amp;gt;Ed Spencer&amp;lt;/name&amp;gt;
  74         &amp;lt;email&amp;gt;ed@sencha.com&amp;lt;/email&amp;gt;
  75     &amp;lt;/user&amp;gt;
  76     &amp;lt;user&amp;gt;
  77         &amp;lt;id&amp;gt;2&amp;lt;/id&amp;gt;
  78         &amp;lt;name&amp;gt;Abe Elias&amp;lt;/name&amp;gt;
  79         &amp;lt;email&amp;gt;abe@sencha.com&amp;lt;/email&amp;gt;
  80     &amp;lt;/user&amp;gt;
  81 &amp;lt;/users&amp;gt;
  82 &lt;/code&gt;&lt;/pre&gt;
  83  *
  84  * &lt;p&gt;To parse this we just pass in a {@link #root} configuration that matches the 'users' above:&lt;/p&gt;
  85  *
  86 &lt;pre&gt;&lt;code&gt;
  87 reader: {
  88     type  : 'xml',
  89     root  : 'users',
  90     record: 'user'
  91 }
  92 &lt;/code&gt;&lt;/pre&gt;
  93  *
  94  * &lt;p&gt;Note that XmlReader doesn't care whether your {@link #root} and {@link #record} elements are nested deep inside
  95  * a larger structure, so a response like this will still work:
  96  *
  97 &lt;pre&gt;&lt;code&gt;
  98 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
  99 &amp;lt;deeply&amp;gt;
 100     &amp;lt;nested&amp;gt;
 101         &amp;lt;xml&amp;gt;
 102             &amp;lt;users&amp;gt;
 103                 &amp;lt;user&amp;gt;
 104                     &amp;lt;id&amp;gt;1&amp;lt;/id&amp;gt;
 105                     &amp;lt;name&amp;gt;Ed Spencer&amp;lt;/name&amp;gt;
 106                     &amp;lt;email&amp;gt;ed@sencha.com&amp;lt;/email&amp;gt;
 107                 &amp;lt;/user&amp;gt;
 108                 &amp;lt;user&amp;gt;
 109                     &amp;lt;id&amp;gt;2&amp;lt;/id&amp;gt;
 110                     &amp;lt;name&amp;gt;Abe Elias&amp;lt;/name&amp;gt;
 111                     &amp;lt;email&amp;gt;abe@sencha.com&amp;lt;/email&amp;gt;
 112                 &amp;lt;/user&amp;gt;
 113             &amp;lt;/users&amp;gt;
 114         &amp;lt;/xml&amp;gt;
 115     &amp;lt;/nested&amp;gt;
 116 &amp;lt;/deeply&amp;gt;
 117 &lt;/code&gt;&lt;/pre&gt;
 118  *
 119  * &lt;p&gt;&lt;u&gt;Response metadata&lt;/u&gt;&lt;/p&gt;
 120  *
 121  * &lt;p&gt;The server can return additional data in its response, such as the {@link #totalProperty total number of records}
 122  * and the {@link #successProperty success status of the response}. These are typically included in the XML response
 123  * like this:&lt;/p&gt;
 124  *
 125 &lt;pre&gt;&lt;code&gt;
 126 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
 127 &amp;lt;total&amp;gt;100&amp;lt;/total&amp;gt;
 128 &amp;lt;success&amp;gt;true&amp;lt;/success&amp;gt;
 129 &amp;lt;users&amp;gt;
 130     &amp;lt;user&amp;gt;
 131         &amp;lt;id&amp;gt;1&amp;lt;/id&amp;gt;
 132         &amp;lt;name&amp;gt;Ed Spencer&amp;lt;/name&amp;gt;
 133         &amp;lt;email&amp;gt;ed@sencha.com&amp;lt;/email&amp;gt;
 134     &amp;lt;/user&amp;gt;
 135     &amp;lt;user&amp;gt;
 136         &amp;lt;id&amp;gt;2&amp;lt;/id&amp;gt;
 137         &amp;lt;name&amp;gt;Abe Elias&amp;lt;/name&amp;gt;
 138         &amp;lt;email&amp;gt;abe@sencha.com&amp;lt;/email&amp;gt;
 139     &amp;lt;/user&amp;gt;
 140 &amp;lt;/users&amp;gt;
 141 &lt;/code&gt;&lt;/pre&gt;
 142  *
 143  * &lt;p&gt;If these properties are present in the XML response they can be parsed out by the XmlReader and used by the
 144  * Store that loaded it. We can set up the names of these properties by specifying a final pair of configuration
 145  * options:&lt;/p&gt;
 146  *
 147 &lt;pre&gt;&lt;code&gt;
 148 reader: {
 149     type: 'xml',
 150     root: 'users',
 151     totalProperty  : 'total',
 152     successProperty: 'success'
 153 }
 154 &lt;/code&gt;&lt;/pre&gt;
 155  *
 156  * &lt;p&gt;These final options are not necessary to make the Reader work, but can be useful when the server needs to report
 157  * an error or if it needs to indicate that there is a lot of data available of which only a subset is currently being
 158  * returned.&lt;/p&gt;
 159  *
 160  * &lt;p&gt;&lt;u&gt;Response format&lt;/u&gt;&lt;/p&gt;
 161  *
 162  * &lt;p&gt;&lt;b&gt;Note:&lt;/b&gt; in order for the browser to parse a returned XML document, the Content-Type header in the HTTP
 163  * response must be set to &quot;text/xml&quot; or &quot;application/xml&quot;. This is very important - the XmlReader will not
 164  * work correctly otherwise.&lt;/p&gt;
 165  */
 166 Ext.define('Ext.data.reader.Xml', {
 167     extend: 'Ext.data.reader.Reader',
 168     alternateClassName: 'Ext.data.XmlReader',
 169     alias : 'reader.xml',
 170
 171 <span id='Ext-data.reader.Xml-property-'>    /**
 172 </span>     * @private
 173      * Creates a function to return some particular key of data from a response. The totalProperty and
 174      * successProperty are treated as special cases for type casting, everything else is just a simple selector.
 175      * @param {String} key
 176      * @return {Function}
 177      */
 178
 179 <span id='Ext-data.reader.Xml-cfg-record'>    /**
 180 </span>     * @cfg {String} record The DomQuery path to the repeated element which contains record information.
 181      */
 182
 183     createAccessor: function() {
 184         var selectValue = function(expr, root){
 185             var node = Ext.DomQuery.selectNode(expr, root),
 186                 val;
 187
 188
 189
 190         };
 191
 192         return function(expr) {
 193             var me = this;
 194
 195             if (Ext.isEmpty(expr)) {
 196                 return Ext.emptyFn;
 197             }
 198
 199             if (Ext.isFunction(expr)) {
 200                 return expr;
 201             }
 202
 203             return function(root) {
 204                 var node = Ext.DomQuery.selectNode(expr, root),
 205                     val = me.getNodeValue(node);
 206
 207                 return Ext.isEmpty(val) ? null : val;
 208             };
 209         };
 210     }(),
 211
 212     getNodeValue: function(node) {
 213         var val;
 214         if (node &amp;&amp; node.firstChild) {
 215             val = node.firstChild.nodeValue;
 216         }
 217         return val || null;
 218     },
 219
 220     //inherit docs
 221     getResponseData: function(response) {
 222         var xml = response.responseXML;
 223
 224         //&lt;debug&gt;
 225         if (!xml) {
 226             Ext.Error.raise({
 227                 response: response,
 228                 msg: 'XML data not found in the response'
 229             });
 230         }
 231         //&lt;/debug&gt;
 232
 233         return xml;
 234     },
 235
 236 <span id='Ext-data.reader.Xml-method-getData'>    /**
 237 </span>     * Normalizes the data object
 238      * @param {Object} data The raw data object
 239      * @return {Object} Returns the documentElement property of the data object if present, or the same object if not
 240      */
 241     getData: function(data) {
 242         return data.documentElement || data;
 243     },
 244
 245 <span id='Ext-data.reader.Xml-method-getRoot'>    /**
 246 </span>     * @private
 247      * Given an XML object, returns the Element that represents the root as configured by the Reader's meta data
 248      * @param {Object} data The XML data object
 249      * @return {Element} The root node element
 250      */
 251     getRoot: function(data) {
 252         var nodeName = data.nodeName,
 253             root     = this.root;
 254
 255         if (!root || (nodeName &amp;&amp; nodeName == root)) {
 256             return data;
 257         } else if (Ext.DomQuery.isXml(data)) {
 258             // This fix ensures we have XML data
 259             // Related to TreeStore calling getRoot with the root node, which isn't XML
 260             // Probably should be resolved in TreeStore at some point
 261             return Ext.DomQuery.selectNode(root, data);
 262         }
 263     },
 264
 265 <span id='Ext-data.reader.Xml-method-extractData'>    /**
 266 </span>     * @private
 267      * We're just preparing the data for the superclass by pulling out the record nodes we want
 268      * @param {Element} root The XML root node
 269      * @return {Array} The records
 270      */
 271     extractData: function(root) {
 272         var recordName = this.record;
 273
 274         //&lt;debug&gt;
 275         if (!recordName) {
 276             Ext.Error.raise('Record is a required parameter');
 277         }
 278         //&lt;/debug&gt;
 279
 280         if (recordName != root.nodeName) {
 281             root = Ext.DomQuery.select(recordName, root);
 282         } else {
 283             root = [root];
 284         }
 285         return this.callParent([root]);
 286     },
 287
 288 <span id='Ext-data.reader.Xml-method-getAssociatedDataRoot'>    /**
 289 </span>     * @private
 290      * See Ext.data.reader.Reader's getAssociatedDataRoot docs
 291      * @param {Mixed} data The raw data object
 292      * @param {String} associationName The name of the association to get data for (uses associationKey if present)
 293      * @return {Mixed} The root
 294      */
 295     getAssociatedDataRoot: function(data, associationName) {
 296         return Ext.DomQuery.select(associationName, data)[0];
 297     },
 298
 299 <span id='Ext-data.reader.Xml-method-readRecords'>    /**
 300 </span>     * Parses an XML document and returns a ResultSet containing the model instances
 301      * @param {Object} doc Parsed XML document
 302      * @return {Ext.data.ResultSet} The parsed result set
 303      */
 304     readRecords: function(doc) {
 305         //it's possible that we get passed an array here by associations. Make sure we strip that out (see Ext.data.reader.Reader#readAssociated)
 306         if (Ext.isArray(doc)) {
 307             doc = doc[0];
 308         }
 309
 310 <span id='Ext-data.reader.Xml-property-xmlData'>        /**
 311 </span>         * DEPRECATED - will be removed in Ext JS 5.0. This is just a copy of this.rawData - use that instead
 312          * @property xmlData
 313          * @type Object
 314          */
 315         this.xmlData = doc;
 316         return this.callParent([doc]);
 317     }
 318 });
 319 </pre></pre></body></html>