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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/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 = Ext.create('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 (required)
 190      * The DomQuery path to the repeated element which contains record information.
 191      */
 192
 193 <span id='Ext-data-reader-Xml-method-createAccessor'>    /**
 194 </span>     * @private
 195      * Creates a function to return some particular key of data from a response. The totalProperty and
 196      * successProperty are treated as special cases for type casting, everything else is just a simple selector.
 197      * @param {String} key
 198      * @return {Function}
 199      */
 200     createAccessor: function(expr) {
 201         var me = this;
 202
 203         if (Ext.isEmpty(expr)) {
 204             return Ext.emptyFn;
 205         }
 206
 207         if (Ext.isFunction(expr)) {
 208             return expr;
 209         }
 210
 211         return function(root) {
 212             return me.getNodeValue(Ext.DomQuery.selectNode(expr, root));
 213         };
 214     },
 215
 216     getNodeValue: function(node) {
 217         if (node &amp;&amp; node.firstChild) {
 218             return node.firstChild.nodeValue;
 219         }
 220         return undefined;
 221     },
 222
 223     //inherit docs
 224     getResponseData: function(response) {
 225         var xml = response.responseXML;
 226
 227         //&lt;debug&gt;
 228         if (!xml) {
 229             Ext.Error.raise({
 230                 response: response,
 231                 msg: 'XML data not found in the response'
 232             });
 233         }
 234         //&lt;/debug&gt;
 235
 236         return xml;
 237     },
 238
 239 <span id='Ext-data-reader-Xml-method-getData'>    /**
 240 </span>     * Normalizes the data object
 241      * @param {Object} data The raw data object
 242      * @return {Object} Returns the documentElement property of the data object if present, or the same object if not
 243      */
 244     getData: function(data) {
 245         return data.documentElement || data;
 246     },
 247
 248 <span id='Ext-data-reader-Xml-method-getRoot'>    /**
 249 </span>     * @private
 250      * Given an XML object, returns the Element that represents the root as configured by the Reader's meta data
 251      * @param {Object} data The XML data object
 252      * @return {XMLElement} The root node element
 253      */
 254     getRoot: function(data) {
 255         var nodeName = data.nodeName,
 256             root     = this.root;
 257
 258         if (!root || (nodeName &amp;&amp; nodeName == root)) {
 259             return data;
 260         } else if (Ext.DomQuery.isXml(data)) {
 261             // This fix ensures we have XML data
 262             // Related to TreeStore calling getRoot with the root node, which isn't XML
 263             // Probably should be resolved in TreeStore at some point
 264             return Ext.DomQuery.selectNode(root, data);
 265         }
 266     },
 267
 268 <span id='Ext-data-reader-Xml-method-extractData'>    /**
 269 </span>     * @private
 270      * We're just preparing the data for the superclass by pulling out the record nodes we want
 271      * @param {XMLElement} root The XML root node
 272      * @return {Ext.data.Model[]} The records
 273      */
 274     extractData: function(root) {
 275         var recordName = this.record;
 276
 277         //&lt;debug&gt;
 278         if (!recordName) {
 279             Ext.Error.raise('Record is a required parameter');
 280         }
 281         //&lt;/debug&gt;
 282
 283         if (recordName != root.nodeName) {
 284             root = Ext.DomQuery.select(recordName, root);
 285         } else {
 286             root = [root];
 287         }
 288         return this.callParent([root]);
 289     },
 290
 291 <span id='Ext-data-reader-Xml-method-getAssociatedDataRoot'>    /**
 292 </span>     * @private
 293      * See Ext.data.reader.Reader's getAssociatedDataRoot docs
 294      * @param {Object} data The raw data object
 295      * @param {String} associationName The name of the association to get data for (uses associationKey if present)
 296      * @return {XMLElement} The root
 297      */
 298     getAssociatedDataRoot: function(data, associationName) {
 299         return Ext.DomQuery.select(associationName, data)[0];
 300     },
 301
 302 <span id='Ext-data-reader-Xml-method-readRecords'>    /**
 303 </span>     * Parses an XML document and returns a ResultSet containing the model instances
 304      * @param {Object} doc Parsed XML document
 305      * @return {Ext.data.ResultSet} The parsed result set
 306      */
 307     readRecords: function(doc) {
 308         //it's possible that we get passed an array here by associations. Make sure we strip that out (see Ext.data.reader.Reader#readAssociated)
 309         if (Ext.isArray(doc)) {
 310             doc = doc[0];
 311         }
 312
 313 <span id='Ext-data-reader-Xml-property-xmlData'>        /**
 314 </span>         * @deprecated will be removed in Ext JS 5.0. This is just a copy of this.rawData - use that instead
 315          * @property xmlData
 316          * @type Object
 317          */
 318         this.xmlData = doc;
 319         return this.callParent([doc]);
 320     }
 321 });</pre>
 322 </body>
 323 </html>