Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Xml.html
index 567099b..e8d7cea 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
 </span> * @author Ed Spencer
  * @class Ext.data.reader.Xml
  * @extends Ext.data.reader.Reader
- * 
+ *
  * &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
  * happens as a result of loading a Store - for example we might create something like this:&lt;/p&gt;
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 Ext.define('User', {
     extend: 'Ext.data.Model',
     fields: ['id', 'name', 'email']
 });
 
-var store = new Ext.data.Store({
+var store = Ext.create('Ext.data.Store', {
     model: 'User',
     proxy: {
         type: 'ajax',
@@ -41,14 +41,14 @@ var store = new Ext.data.Store({
     }
 });
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;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.&lt;/p&gt;
- * 
- * &lt;p&gt;We created the simplest type of XML Reader possible by simply telling our {@link Ext.data.Store Store}'s 
+ *
+ * &lt;p&gt;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:
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 reader: {
     type : 'xml',
@@ -56,7 +56,7 @@ reader: {
     record: 'user'
 }
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &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;
  *
 &lt;pre&gt;&lt;code&gt;
@@ -72,16 +72,16 @@ reader: {
     &amp;lt;email&amp;gt;abe@sencha.com&amp;lt;/email&amp;gt;
 &amp;lt;/user&amp;gt;
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;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 &amp;lt;user&amp;gt; above will be converted into a User model.&lt;/p&gt;
- * 
+ *
  * &lt;p&gt;&lt;u&gt;Reading other XML formats&lt;/u&gt;&lt;/p&gt;
- * 
+ *
  * &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
- * pass XmlReader a couple of configuration options to make it parse your format. For example, we can use the 
+ * 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:&lt;/p&gt;
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
 &amp;lt;users&amp;gt;
@@ -97,9 +97,9 @@ reader: {
     &amp;lt;/user&amp;gt;
 &amp;lt;/users&amp;gt;
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;To parse this we just pass in a {@link #root} configuration that matches the 'users' above:&lt;/p&gt;
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 reader: {
     type  : 'xml',
@@ -107,10 +107,10 @@ reader: {
     record: 'user'
 }
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;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:
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
 &amp;lt;deeply&amp;gt;
@@ -132,13 +132,13 @@ reader: {
     &amp;lt;/nested&amp;gt;
 &amp;lt;/deeply&amp;gt;
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;&lt;u&gt;Response metadata&lt;/u&gt;&lt;/p&gt;
- * 
- * &lt;p&gt;The server can return additional data in its response, such as the {@link #totalProperty total number of records} 
+ *
+ * &lt;p&gt;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:&lt;/p&gt;
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 &amp;lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&amp;gt;
 &amp;lt;total&amp;gt;100&amp;lt;/total&amp;gt;
@@ -156,11 +156,11 @@ reader: {
     &amp;lt;/user&amp;gt;
 &amp;lt;/users&amp;gt;
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;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 
+ * Store that loaded it. We can set up the names of these properties by specifying a final pair of configuration
  * options:&lt;/p&gt;
- * 
+ *
 &lt;pre&gt;&lt;code&gt;
 reader: {
     type: 'xml',
@@ -169,14 +169,14 @@ reader: {
     successProperty: 'success'
 }
 &lt;/code&gt;&lt;/pre&gt;
- * 
+ *
  * &lt;p&gt;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.&lt;/p&gt;
- * 
+ *
  * &lt;p&gt;&lt;u&gt;Response format&lt;/u&gt;&lt;/p&gt;
- * 
- * &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 
+ *
+ * &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
  * response must be set to &quot;text/xml&quot; or &quot;application/xml&quot;. This is very important - the XmlReader will not
  * work correctly otherwise.&lt;/p&gt;
  */
@@ -184,9 +184,10 @@ Ext.define('Ext.data.reader.Xml', {
     extend: 'Ext.data.reader.Reader',
     alternateClassName: 'Ext.data.XmlReader',
     alias : 'reader.xml',
-    
+
 <span id='Ext-data-reader-Xml-cfg-record'>    /**
-</span>     * @cfg {String} record The DomQuery path to the repeated element which contains record information.
+</span>     * @cfg {String} record (required)
+     * The DomQuery path to the repeated element which contains record information.
      */
 
 <span id='Ext-data-reader-Xml-method-createAccessor'>    /**
@@ -198,29 +199,25 @@ Ext.define('Ext.data.reader.Xml', {
      */
     createAccessor: 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;
+            return me.getNodeValue(Ext.DomQuery.selectNode(expr, root));
         };
     },
-    
+
     getNodeValue: function(node) {
-        var val;
         if (node &amp;&amp; node.firstChild) {
-            val = node.firstChild.nodeValue;
+            return node.firstChild.nodeValue;
         }
-        return val || null;
+        return undefined;
     },
 
     //inherit docs
@@ -252,12 +249,12 @@ Ext.define('Ext.data.reader.Xml', {
 </span>     * @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
+     * @return {XMLElement} The root node element
      */
     getRoot: function(data) {
         var nodeName = data.nodeName,
             root     = this.root;
-        
+
         if (!root || (nodeName &amp;&amp; nodeName == root)) {
             return data;
         } else if (Ext.DomQuery.isXml(data)) {
@@ -271,18 +268,18 @@ Ext.define('Ext.data.reader.Xml', {
 <span id='Ext-data-reader-Xml-method-extractData'>    /**
 </span>     * @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
+     * @param {XMLElement} root The XML root node
+     * @return {Ext.data.Model[]} The records
      */
     extractData: function(root) {
         var recordName = this.record;
-        
+
         //&lt;debug&gt;
         if (!recordName) {
             Ext.Error.raise('Record is a required parameter');
         }
         //&lt;/debug&gt;
-        
+
         if (recordName != root.nodeName) {
             root = Ext.DomQuery.select(recordName, root);
         } else {
@@ -290,13 +287,13 @@ Ext.define('Ext.data.reader.Xml', {
         }
         return this.callParent([root]);
     },
-    
+
 <span id='Ext-data-reader-Xml-method-getAssociatedDataRoot'>    /**
 </span>     * @private
      * See Ext.data.reader.Reader's getAssociatedDataRoot docs
-     * @param {Mixed} data The raw data object
+     * @param {Object} 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
+     * @return {XMLElement} The root
      */
     getAssociatedDataRoot: function(data, associationName) {
         return Ext.DomQuery.select(associationName, data)[0];
@@ -312,16 +309,15 @@ Ext.define('Ext.data.reader.Xml', {
         if (Ext.isArray(doc)) {
             doc = doc[0];
         }
-        
+
 <span id='Ext-data-reader-Xml-property-xmlData'>        /**
-</span>         * DEPRECATED - will be removed in Ext JS 5.0. This is just a copy of this.rawData - use that instead
+</span>         * @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 this.callParent([doc]);
     }
-});
-</pre>
+});</pre>
 </body>
 </html>