docs/source/Xml.html

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