docs/api/Ext.data.reader.Reader.html

   1 <!DOCTYPE html><html><head><title>Ext.data.reader.Reader | Ext JS 4.0 Documentation</title><script type="text/javascript" src="../ext-all.js"></script><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../scrollbars.css" type="text/css"><link rel="stylesheet" href="../docs.css" type="text/css"><link id="styleCss" rel="stylesheet" href="../style.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script><link rel="stylesheet" href="../prettify.css" type="text/css"><!-- link(rel: 'stylesheet', href: req.baseURL + '/css/ext4.css', type: 'text/css')--><link rel="shortcut icon" type="image/ico" href="../favicon.ico"><!--[if IE]>
   2 <style type="text/css">.head-band { display: none; }
   3 .header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
   4 .doc-tab .members .member a.more { background-color: #efefef; }
   5 </style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
   6 </head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit
   7 <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a></div><div class="wrapper"><div class="head-band"></div><div class="header"><h2><a href="../index.html">Sencha Documentation</a></h2></div><div id="search"><form><input type="text" placeholder="Search" id="search-field" autocomplete="off" name="q"></form><div id="search-box"></div></div><div id="treePanel"></div><div id="container"><script type="text/javascript">
   8
   9     req = {
  10         liveURL: '.',
  11         standAloneMode: true,
  12         origDocClass: 'Ext.data.reader.Reader',
  13         docClass: 'Ext.data.reader.Reader',
  14         docReq: 'Ext.data.reader.Reader',
  15         version: '4.0',
  16         baseURL: '.',
  17         baseDocURL: '.',
  18         baseProdURL: '.'
  19     };
  20
  21     clsInfo = {};
  22
  23
  24
  25 </script>
  26
  27 <script type="text/javascript" src="../search.js"></script>
  28 <!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
  29 <script type="text/javascript" src="../class_tree.js"></script>
  30 <script type="text/javascript" src="../class_doc.js"></script>
  31 <script type="text/javascript">
  32     req.source = 'Reader.html#Ext-data.reader.Reader';
  33     clsInfo = {"methods":["Reader","getResponseData","read","readRecords"],"cfgs":["idProperty","implicitIncludes","messageProperty","root","successProperty","totalProperty"],"properties":["rawData"],"events":[],"subclasses":["Ext.data.reader.Json","Ext.data.reader.Xml"]};
  34     Ext.onReady(function() {
  35         Ext.create('Docs.classPanel');
  36     });
  37 </script><div id="top-block" class="top-block"><h1 id="clsTitle" class="cls"><a href="../source/Reader.html#Ext-data.reader.Reader" target="_blank">Ext.data.reader.Reader</a></h1></div><div id="docContent"><div id="doc-overview-content"><div class="lft"><p>Readers are used to interpret data to be loaded into a <a href="Ext.data.Model.html" rel="Ext.data.Model" class="docClass">Model</a> instance or a <a href="Ext.data.Store.html" rel="Ext.data.Store" class="docClass">Store</a>
  38 - usually in response to an AJAX request. This is normally handled transparently by passing some configuration to either the
  39 <a href="Ext.data.Model.html" rel="Ext.data.Model" class="docClass">Model</a> or the <a href="Ext.data.Store.html" rel="Ext.data.Store" class="docClass">Store</a> in question - see their documentation for further details.</p>
  40
  41
  42
  43
  44 <p><u>Loading Nested Data</u></p>
  45
  46
  47
  48
  49 <p>Readers have the ability to automatically load deeply-nested data objects based on the <a href="Ext.data.Association.html" rel="Ext.data.Association" class="docClass">associations</a>
  50 configured on each Model. Below is an example demonstrating the flexibility of these associations in a fictional CRM system which
  51 manages a User, their Orders, OrderItems and Products. First we'll define the models:
  52
  53 <pre class="prettyprint"><code>Ext.define("User", {
  54     extend: 'Ext.data.Model',
  55     fields: [
  56         'id', 'name'
  57     ],
  58
  59     hasMany: {model: 'Order', name: 'orders'},
  60
  61     proxy: {
  62         type: 'rest',
  63         url : 'users.json',
  64         reader: {
  65             type: 'json',
  66             root: 'users'
  67         }
  68     }
  69 });
  70
  71 Ext.define("Order", {
  72     extend: 'Ext.data.Model',
  73     fields: [
  74         'id', 'total'
  75     ],
  76
  77     hasMany  : {model: 'OrderItem', name: 'orderItems', associationKey: 'order_items'},
  78     belongsTo: 'User'
  79 });
  80
  81 Ext.define("OrderItem", {
  82     extend: 'Ext.data.Model',
  83     fields: [
  84         'id', 'price', 'quantity', 'order_id', 'product_id'
  85     ],
  86
  87     belongsTo: ['Order', {model: 'Product', associationKey: 'product'}]
  88 });
  89
  90 Ext.define("Product", {
  91     extend: 'Ext.data.Model',
  92     fields: [
  93         'id', 'name'
  94     ],
  95
  96     hasMany: 'OrderItem'
  97 });
  98 </code></pre>
  99
 100 <p>This may be a lot to take in - basically a User has many Orders, each of which is composed of several OrderItems. Finally,
 101 each OrderItem has a single Product. This allows us to consume data like this:</p>
 102
 103 <pre class="prettyprint"><code>{
 104     "users": [
 105         {
 106             "id": 123,
 107             "name": "Ed",
 108             "orders": [
 109                 {
 110                     "id": 50,
 111                     "total": 100,
 112                     "order_items": [
 113                         {
 114                             "id"      : 20,
 115                             "price"   : 40,
 116                             "quantity": 2,
 117                             "product" : {
 118                                 "id": 1000,
 119                                 "name": "MacBook Pro"
 120                             }
 121                         },
 122                         {
 123                             "id"      : 21,
 124                             "price"   : 20,
 125                             "quantity": 3,
 126                             "product" : {
 127                                 "id": 1001,
 128                                 "name": "iPhone"
 129                             }
 130                         }
 131                     ]
 132                 }
 133             ]
 134         }
 135     ]
 136 }
 137 </code></pre>
 138
 139 <p>The JSON response is deeply nested - it returns all Users (in this case just 1 for simplicity's sake), all of the Orders
 140 for each User (again just 1 in this case), all of the OrderItems for each Order (2 order items in this case), and finally
 141 the Product associated with each OrderItem. Now we can read the data and use it as follows:
 142
 143 <pre class="prettyprint"><code>var store = new Ext.data.Store({
 144     model: "User"
 145 });
 146
 147 store.load({
 148     callback: function() {
 149         //the user that was loaded
 150         var user = store.first();
 151
 152         console.log("Orders for " + user.get('name') + ":")
 153
 154         //iterate over the Orders for each User
 155         user.orders().each(function(order) {
 156             console.log("Order ID: " + order.getId() + ", which contains items:");
 157
 158             //iterate over the OrderItems for each Order
 159             order.orderItems().each(function(orderItem) {
 160                 //we know that the Product data is already loaded, so we can use the synchronous getProduct
 161                 //usually, we would use the asynchronous version (see <a href="Ext.data.BelongsToAssociation.html" rel="Ext.data.BelongsToAssociation" class="docClass">Ext.data.BelongsToAssociation</a>)
 162                 var product = orderItem.getProduct();
 163
 164                 console.log(orderItem.get('quantity') + ' orders of ' + product.get('name'));
 165             });
 166         });
 167     }
 168 });
 169 </code></pre>
 170
 171 <p>Running the code above results in the following:</p>
 172
 173 <pre class="prettyprint"><code>Orders for Ed:
 174 Order ID: 50, which contains items:
 175 2 orders of MacBook Pro
 176 3 orders of iPhone
 177 </code></pre>
 178
 179 <div class="members"><div class="m-cfgs"><div class="definedBy">Defined By</div><a name="configs"></a><h3 class="cfg p">Config Options</h3><h4 class="cfgGroup">Other Configs</h4><div id="config-idProperty" class="member f ni"><a href="Ext.data.reader.Reader.html#config-idProperty" rel="config-idProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-idProperty" class="viewSource">view source</a></div><a name="idProperty"></a><a name="config-idProperty"></a><a href="Ext.data.reader.Reader.html#" rel="config-idProperty" class="cls expand">idProperty</a><span> : String</span></div><div class="description"><div class="short">Name of the property within a row object
 180 that contains a record identifier value.  Defaults to The id of the model.
 181 I...</div><div class="long"><p>Name of the property within a row object
 182 that contains a record identifier value.  Defaults to <tt>The id of the model</tt>.
 183 If an idProperty is explicitly specified it will override that of the one specified
 184 on the model</p>
 185 </div></div></div><div id="config-implicitIncludes" class="member ni"><a href="Ext.data.reader.Reader.html#config-implicitIncludes" rel="config-implicitIncludes" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-implicitIncludes" class="viewSource">view source</a></div><a name="implicitIncludes"></a><a name="config-implicitIncludes"></a><a href="Ext.data.reader.Reader.html#" rel="config-implicitIncludes" class="cls expand">implicitIncludes</a><span> : Boolean</span></div><div class="description"><div class="short">True to automatically parse models nested within other models in a response
 186 object. See the Ext.data.reader.Reader in...</div><div class="long"><p>True to automatically parse models nested within other models in a response
 187 object. See the <a href="Ext.data.reader.Reader.html" rel="Ext.data.reader.Reader" class="docClass">Ext.data.reader.Reader</a> intro docs for full explanation. Defaults to true.</p>
 188 </div></div></div><div id="config-messageProperty" class="member ni"><a href="Ext.data.reader.Reader.html#config-messageProperty" rel="config-messageProperty" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-messageProperty" class="viewSource">view source</a></div><a name="messageProperty"></a><a name="config-messageProperty"></a><a href="Ext.data.reader.Reader.html#" rel="config-messageProperty" class="cls expand">messageProperty</a><span> : String</span></div><div class="description"><div class="short"><p>The name of the property which contains a response message.
 189 This property is optional.</p>
 190 </div><div class="long"><p>The name of the property which contains a response message.
 191 This property is optional.</p>
 192 </div></div></div><div id="config-root" class="member ni"><a href="Ext.data.reader.Reader.html#config-root" rel="config-root" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-root" class="viewSource">view source</a></div><a name="root"></a><a name="config-root"></a><a href="Ext.data.reader.Reader.html#" rel="config-root" class="cls expand">root</a><span> : String</span></div><div class="description"><div class="short">Required.  The name of the property
 193 which contains the Array of row objects.  Defaults to undefined.
 194 An exception wil...</div><div class="long"><p><b>Required</b>.  The name of the property
 195 which contains the Array of row objects.  Defaults to <tt>undefined</tt>.
 196 An exception will be thrown if the root property is undefined. The data
 197 packet value for this property should be an empty array to clear the data
 198 or show no data.</p>
 199 </div></div></div><div id="config-successProperty" class="member ni"><a href="Ext.data.reader.Reader.html#config-successProperty" rel="config-successProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-successProperty" class="viewSource">view source</a></div><a name="successProperty"></a><a name="config-successProperty"></a><a href="Ext.data.reader.Reader.html#" rel="config-successProperty" class="cls expand">successProperty</a><span> : String</span></div><div class="description"><div class="short">Name of the property from which to
 200 retrieve the success attribute. Defaults to success.  See
 201 Ext.data.proxy.Proxy.exc...</div><div class="long"><p>Name of the property from which to
 202 retrieve the success attribute. Defaults to <tt>success</tt>.  See
 203 <a href="Ext.data.proxy.Proxy.html" rel="Ext.data.proxy.Proxy" class="docClass">Ext.data.proxy.Proxy</a>.<a href="Ext.data.proxy.Proxy.html#exception" rel="Ext.data.proxy.Proxy#exception" class="docClass">exception</a>
 204 for additional information.</p>
 205 </div></div></div><div id="config-totalProperty" class="member ni"><a href="Ext.data.reader.Reader.html#config-totalProperty" rel="config-totalProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-cfg-totalProperty" class="viewSource">view source</a></div><a name="totalProperty"></a><a name="config-totalProperty"></a><a href="Ext.data.reader.Reader.html#" rel="config-totalProperty" class="cls expand">totalProperty</a><span> : String</span></div><div class="description"><div class="short">Name of the property from which to
 206 retrieve the total number of records in the dataset. This is only needed
 207 if the wh...</div><div class="long"><p>Name of the property from which to
 208 retrieve the total number of records in the dataset. This is only needed
 209 if the whole dataset is not passed in one go, but is being paged from
 210 the remote server.  Defaults to <tt>total</tt>.</p>
 211 </div></div></div></div><div class="m-properties"><a name="properties"></a><div class="definedBy">Defined By</div><h3 class="prp p">Properties</h3><div id="property-rawData" class="member f ni"><a href="Ext.data.reader.Reader.html#property-rawData" rel="property-rawData" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-property-rawData" class="viewSource">view source</a></div><a name="rawData"></a><a name="property-rawData"></a><a href="Ext.data.reader.Reader.html#" rel="property-rawData" class="cls expand">rawData</a><span> : Mixed</span></div><div class="description"><div class="short"><p>The raw data object that was last passed to readRecords. Stored for further processing if needed</p>
 212 </div><div class="long"><p>The raw data object that was last passed to readRecords. Stored for further processing if needed</p>
 213 </div></div></div></div><div class="m-methods"><a name="methods"></a><div class="definedBy">Defined By</div><h3 class="mth p">Methods</h3><div id="method-Reader" class="member f ni"><a href="Ext.data.reader.Reader.html#method-Reader" rel="method-Reader" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-constructor" class="viewSource">view source</a></div><a name="Reader"></a><a name="method-Reader"></a><a href="Ext.data.reader.Reader.html#" rel="method-Reader" class="cls expand">Reader</a>(
 214 <span class="pre">Object config</span>)
 215  : void</div><div class="description"><div class="short"><p>&nbsp;</p></div><div class="long">
 216 <h3 class="pa">Parameters</h3><ul><li><span class="pre">config</span> : Object<div class="sub-desc"><p>Optional config object</p>
 217 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
 218 </li></ul></div></div></div><div id="method-getResponseData" class="member ni"><a href="Ext.data.reader.Reader.html#method-getResponseData" rel="method-getResponseData" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-getResponseData" class="viewSource">view source</a></div><a name="getResponseData"></a><a name="method-getResponseData"></a><a href="Ext.data.reader.Reader.html#" rel="method-getResponseData" class="cls expand">getResponseData</a>(
 219 <span class="pre">Object response</span>)
 220  : Object</div><div class="description"><div class="short">Takes a raw response object (as passed to this.read) and returns the useful data segment of it. This must be implemen...</div><div class="long"><p>Takes a raw response object (as passed to this.read) and returns the useful data segment of it. This must be implemented by each subclass</p>
 221 <h3 class="pa">Parameters</h3><ul><li><span class="pre">response</span> : Object<div class="sub-desc"><p>The responce object</p>
 222 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Object</span>&nbsp; &nbsp;<p>The useful data from the response</p>
 223 </li></ul></div></div></div><div id="method-read" class="member ni"><a href="Ext.data.reader.Reader.html#method-read" rel="method-read" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-read" class="viewSource">view source</a></div><a name="read"></a><a name="method-read"></a><a href="Ext.data.reader.Reader.html#" rel="method-read" class="cls expand">read</a>(
 224 <span class="pre">Object response</span>)
 225  : Ext.data.ResultSet</div><div class="description"><div class="short">Reads the given response object. This method normalizes the different types of response object that may be passed
 226 to ...</div><div class="long"><p>Reads the given response object. This method normalizes the different types of response object that may be passed
 227 to it, before handing off the reading of records to the <a href="Ext.data.reader.Reader.html#readRecords" rel="Ext.data.reader.Reader#readRecords" class="docClass">readRecords</a> function.</p>
 228 <h3 class="pa">Parameters</h3><ul><li><span class="pre">response</span> : Object<div class="sub-desc"><p>The response object. This may be either an XMLHttpRequest object or a plain JS object</p>
 229 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Ext.data.ResultSet</span>&nbsp; &nbsp;<p>The parsed ResultSet object</p>
 230 </li></ul></div></div></div><div id="method-readRecords" class="member ni"><a href="Ext.data.reader.Reader.html#method-readRecords" rel="method-readRecords" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.reader.Reader.html" class="definedIn docClass">Ext.data.reader.Reader</a><br/><a href="../source/Reader.html#Ext-data.reader.Reader-method-readRecords" class="viewSource">view source</a></div><a name="readRecords"></a><a name="method-readRecords"></a><a href="Ext.data.reader.Reader.html#" rel="method-readRecords" class="cls expand">readRecords</a>(
 231 <span class="pre">Mixed data</span>)
 232  : Ext.data.ResultSet</div><div class="description"><div class="short">Abstracts common functionality used by all Reader subclasses. Each subclass is expected to call
 233 this function before ...</div><div class="long"><p>Abstracts common functionality used by all Reader subclasses. Each subclass is expected to call
 234 this function before running its own logic and returning the <a href="Ext.data.ResultSet.html" rel="Ext.data.ResultSet" class="docClass">Ext.data.ResultSet</a> instance. For most
 235 Readers additional processing should not be needed.</p>
 236 <h3 class="pa">Parameters</h3><ul><li><span class="pre">data</span> : Mixed<div class="sub-desc"><p>The raw data object</p>
 237 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Ext.data.ResultSet</span>&nbsp; &nbsp;<p>A ResultSet object</p>
 238 </li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>