docs/api/Ext.data.HasManyAssociation.html

   1 <!DOCTYPE html><html><head><title>Ext.data.HasManyAssociation | 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.HasManyAssociation',
  13         docClass: 'Ext.data.HasManyAssociation',
  14         docReq: 'Ext.data.HasManyAssociation',
  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 = 'HasManyAssociation.html#Ext-data.HasManyAssociation';
  33     clsInfo = {"methods":["HasManyAssociation","getReader"],"cfgs":["associatedModel","associationKey","autoLoad","filterProperty","foreignKey","name","ownerModel","primaryKey","reader","storeConfig","type"],"properties":["associatedName","ownerName"],"events":[],"subclasses":[]};
  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/HasManyAssociation.html#Ext-data.HasManyAssociation" target="_blank">Ext.data.HasManyAssociation</a></h1></div><div id="docContent"><div id="doc-overview-content"><div class="lft"><pre class="subclasses"><h4>Hierarchy</h4><div class="subclass f"><a href="Ext.data.Association.html" rel="Ext.data.Association" class="cls docClass">Ext.data.Association</a><div class="subclass"><strong>Ext.data.HasManyAssociation</strong></div></div></pre><p>Represents a one-to-many relationship between two models. Usually created indirectly via a model definition:</p>
  38
  39
  40
  41
  42 <pre class="prettyprint"><code>Ext.define('Product', {
  43     extend: 'Ext.data.Model',
  44     fields: [
  45         {name: 'id',      type: 'int'},
  46         {name: 'user_id', type: 'int'},
  47         {name: 'name',    type: 'string'}
  48     ]
  49 });
  50
  51 Ext.define('User', {
  52     extend: 'Ext.data.Model',
  53     fields: [
  54         {name: 'id',   type: 'int'},
  55         {name: 'name', type: 'string'}
  56     ],
  57     // we can use the hasMany shortcut on the model to create a hasMany association
  58     hasMany: {model: 'Product', name: 'products'}
  59 });
  60 </pre>
  61
  62
  63 <p></code></p>
  64
  65 <p>Above we created Product and User models, and linked them by saying that a User hasMany Products. This gives
  66 us a new function on every User instance, in this case the function is called 'products' because that is the name
  67 we specified in the association configuration above.</p>
  68
  69
  70
  71
  72 <p>This new function returns a specialized <a href="Ext.data.Store.html" rel="Ext.data.Store" class="docClass">Store</a> which is automatically filtered to load
  73 only Products for the given model instance:</p>
  74
  75
  76
  77
  78 <pre class="prettyprint"><code>//first, we load up a User with id of 1
  79 var user = Ext.ModelManager.create({id: 1, name: 'Ed'}, 'User');
  80
  81 //the user.products function was created automatically by the association and returns a <a href="Ext.data.Store.html" rel="Ext.data.Store" class="docClass">Store</a>
  82 //the created store is automatically scoped to the set of Products for the User with id of 1
  83 var products = user.products();
  84
  85 //we still have all of the usual Store functions, for example it's easy to add a Product for this User
  86 products.add({
  87     name: 'Another Product'
  88 });
  89
  90 //saves the changes to the store - this automatically sets the new Product's user_id to 1 before saving
  91 products.sync();
  92 </code></pre>
  93
  94
  95
  96
  97 <p>The new Store is only instantiated the first time you call products() to conserve memory and processing time,
  98 though calling products() a second time returns the same store instance.</p>
  99
 100
 101
 102
 103 <p><u>Custom filtering</u></p>
 104
 105
 106
 107
 108 <p>The Store is automatically furnished with a filter - by default this filter tells the store to only return
 109 records where the associated model's foreign key matches the owner model's primary key. For example, if a User
 110 with ID = 100 hasMany Products, the filter loads only Products with user_id == 100.</p>
 111
 112
 113
 114
 115 <p>Sometimes we want to filter by another field - for example in the case of a Twitter search application we may
 116 have models for Search and Tweet:</p>
 117
 118
 119
 120
 121 <pre class="prettyprint"><code>Ext.define('Search', {
 122     extend: 'Ext.data.Model',
 123     fields: [
 124         'id', 'query'
 125     ],
 126
 127     hasMany: {
 128         model: 'Tweet',
 129         name : 'tweets',
 130         filterProperty: 'query'
 131     }
 132 });
 133
 134 Ext.define('Tweet', {
 135     extend: 'Ext.data.Model',
 136     fields: [
 137         'id', 'text', 'from_user'
 138     ]
 139 });
 140
 141 //returns a Store filtered by the filterProperty
 142 var store = new Search({query: 'Sencha Touch'}).tweets();
 143 </code></pre>
 144
 145
 146
 147
 148 <p>The tweets association above is filtered by the query property by setting the <a href="Ext.data.HasManyAssociation.html#filterProperty" rel="Ext.data.HasManyAssociation#filterProperty" class="docClass">filterProperty</a>, and is
 149 equivalent to this:</p>
 150
 151
 152
 153
 154 <pre class="prettyprint"><code>var store = new Ext.data.Store({
 155     model: 'Tweet',
 156     filters: [
 157         {
 158             property: 'query',
 159             value   : 'Sencha Touch'
 160         }
 161     ]
 162 });
 163 </code></pre>
 164
 165 <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-associatedModel" class="member f inherited"><a href="Ext.data.HasManyAssociation.html#config-associatedModel" rel="config-associatedModel" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-cfg-associatedModel" class="viewSource">view source</a></div><a name="associatedModel"></a><a name="config-associatedModel"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-associatedModel" class="cls expand">associatedModel</a><span> : String</span></div><div class="description"><div class="short"><p>The string name of the model that is being associated with. Required</p>
 166 </div><div class="long"><p>The string name of the model that is being associated with. Required</p>
 167 </div></div></div><div id="config-associationKey" class="member inherited"><a href="Ext.data.HasManyAssociation.html#config-associationKey" rel="config-associationKey" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-cfg-associationKey" class="viewSource">view source</a></div><a name="associationKey"></a><a name="config-associationKey"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-associationKey" class="cls expand">associationKey</a><span> : String</span></div><div class="description"><div class="short"><p>The name of the property in the data to read the association from.
 168 Defaults to the name of the associated model.</p>
 169 </div><div class="long"><p>The name of the property in the data to read the association from.
 170 Defaults to the name of the associated model.</p>
 171 </div></div></div><div id="config-autoLoad" class="member ni"><a href="Ext.data.HasManyAssociation.html#config-autoLoad" rel="config-autoLoad" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.HasManyAssociation.html" class="definedIn docClass">Ext.data.HasManyAssociation</a><br/><a href="../source/HasManyAssociation.html#Ext-data.HasManyAssociation-cfg-autoLoad" class="viewSource">view source</a></div><a name="autoLoad"></a><a name="config-autoLoad"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-autoLoad" class="cls expand">autoLoad</a><span> : Boolean</span></div><div class="description"><div class="short"><p>True to automatically load the related store from a remote source when instantiated.
 172 Defaults to <tt>false</tt>.</p>
 173 </div><div class="long"><p>True to automatically load the related store from a remote source when instantiated.
 174 Defaults to <tt>false</tt>.</p>
 175 </div></div></div><div id="config-filterProperty" class="member ni"><a href="Ext.data.HasManyAssociation.html#config-filterProperty" rel="config-filterProperty" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.HasManyAssociation.html" class="definedIn docClass">Ext.data.HasManyAssociation</a><br/><a href="../source/HasManyAssociation.html#Ext-data.HasManyAssociation-cfg-filterProperty" class="viewSource">view source</a></div><a name="filterProperty"></a><a name="config-filterProperty"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-filterProperty" class="cls expand">filterProperty</a><span> : String</span></div><div class="description"><div class="short">Optionally overrides the default filter that is set up on the associated Store. If
 176 this is not set, a filter is autom...</div><div class="long"><p>Optionally overrides the default filter that is set up on the associated Store. If
 177 this is not set, a filter is automatically created which filters the association based on the configured
 178 <a href="Ext.data.HasManyAssociation.html#foreignKey" rel="Ext.data.HasManyAssociation#foreignKey" class="docClass">foreignKey</a>. See intro docs for more details. Defaults to undefined</p>
 179 </div></div></div><div id="config-foreignKey" class="member ni"><a href="Ext.data.HasManyAssociation.html#config-foreignKey" rel="config-foreignKey" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.HasManyAssociation.html" class="definedIn docClass">Ext.data.HasManyAssociation</a><br/><a href="../source/HasManyAssociation.html#Ext-data.HasManyAssociation-cfg-foreignKey" class="viewSource">view source</a></div><a name="foreignKey"></a><a name="config-foreignKey"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-foreignKey" class="cls expand">foreignKey</a><span> : String</span></div><div class="description"><div class="short">The name of the foreign key on the associated model that links it to the owner
 180 model. Defaults to the lowercased name...</div><div class="long"><p>The name of the foreign key on the associated model that links it to the owner
 181 model. Defaults to the lowercased name of the owner model plus "_id", e.g. an association with a where a
 182 model called Group hasMany Users would create 'group_id' as the foreign key. When the remote store is loaded,
 183 the store is automatically filtered so that only records with a matching foreign key are included in the
 184 resulting child store. This can be overridden by specifying the <a href="Ext.data.HasManyAssociation.html#filterProperty" rel="Ext.data.HasManyAssociation#filterProperty" class="docClass">filterProperty</a>.</p>
 185
 186 <pre><code>Ext.define('Group', {
 187     extend: 'Ext.data.Model',
 188     fields: ['id', 'name'],
 189     hasMany: 'User'
 190 });
 191
 192 Ext.define('User', {
 193     extend: 'Ext.data.Model',
 194     fields: ['id', 'name', 'group_id'], // refers to the id of the group that this user belongs to
 195     belongsTo: 'Group'
 196 });
 197 </code></pre>
 198
 199 </div></div></div><div id="config-name" class="member ni"><a href="Ext.data.HasManyAssociation.html#config-name" rel="config-name" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.HasManyAssociation.html" class="definedIn docClass">Ext.data.HasManyAssociation</a><br/><a href="../source/HasManyAssociation.html#Ext-data.HasManyAssociation-cfg-name" class="viewSource">view source</a></div><a name="name"></a><a name="config-name"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-name" class="cls expand">name</a><span> : String</span></div><div class="description"><div class="short">The name of the function to create on the owner model to retrieve the child store.
 200 If not specified, the pluralized n...</div><div class="long"><p>The name of the function to create on the owner model to retrieve the child store.
 201 If not specified, the pluralized name of the child model is used.</p>
 202
 203 <pre><code>// This will create a users() method on any Group model instance
 204 Ext.define('Group', {
 205     extend: 'Ext.data.Model',
 206     fields: ['id', 'name'],
 207     hasMany: 'User'
 208 });
 209 var group = new Group();
 210 console.log(group.users());
 211
 212 // The method to retrieve the users will now be getUserList
 213 Ext.define('Group', {
 214     extend: 'Ext.data.Model',
 215     fields: ['id', 'name'],
 216     hasMany: {model: 'User', name: 'getUserList'}
 217 });
 218 var group = new Group();
 219 console.log(group.getUserList());
 220 </code></pre>
 221
 222 </div></div></div><div id="config-ownerModel" class="member inherited"><a href="Ext.data.HasManyAssociation.html#config-ownerModel" rel="config-ownerModel" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-cfg-ownerModel" class="viewSource">view source</a></div><a name="ownerModel"></a><a name="config-ownerModel"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-ownerModel" class="cls expand">ownerModel</a><span> : String</span></div><div class="description"><div class="short"><p>The string name of the model that owns the association. Required</p>
 223 </div><div class="long"><p>The string name of the model that owns the association. Required</p>
 224 </div></div></div><div id="config-primaryKey" class="member inherited"><a href="Ext.data.HasManyAssociation.html#config-primaryKey" rel="config-primaryKey" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-cfg-primaryKey" class="viewSource">view source</a></div><a name="primaryKey"></a><a name="config-primaryKey"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-primaryKey" class="cls expand">primaryKey</a><span> : String</span></div><div class="description"><div class="short">The name of the primary key on the associated model. Defaults to 'id'.
 225 In general this will be the Ext.data.Model.idP...</div><div class="long"><p>The name of the primary key on the associated model. Defaults to 'id'.
 226 In general this will be the <a href="Ext.data.Model.html#idProperty" rel="Ext.data.Model#idProperty" class="docClass">Ext.data.Model.idProperty</a> of the Model.</p>
 227 </div></div></div><div id="config-reader" class="member inherited"><a href="Ext.data.HasManyAssociation.html#config-reader" rel="config-reader" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-cfg-reader" class="viewSource">view source</a></div><a name="reader"></a><a name="config-reader"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-reader" class="cls expand">reader</a><span> : Ext.data.reader.Reader</span></div><div class="description"><div class="short"><p>A special reader to read associated data</p>
 228 </div><div class="long"><p>A special reader to read associated data</p>
 229 </div></div></div><div id="config-storeConfig" class="member ni"><a href="Ext.data.HasManyAssociation.html#config-storeConfig" rel="config-storeConfig" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.HasManyAssociation.html" class="definedIn docClass">Ext.data.HasManyAssociation</a><br/><a href="../source/HasManyAssociation.html#Ext-data.HasManyAssociation-cfg-storeConfig" class="viewSource">view source</a></div><a name="storeConfig"></a><a name="config-storeConfig"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-storeConfig" class="cls expand">storeConfig</a><span> : Object</span></div><div class="description"><div class="short"><p>Optional configuration object that will be passed to the generated Store. Defaults to
 230 undefined.</p>
 231 </div><div class="long"><p>Optional configuration object that will be passed to the generated Store. Defaults to
 232 undefined.</p>
 233 </div></div></div><div id="config-type" class="member ni"><a href="Ext.data.HasManyAssociation.html#config-type" rel="config-type" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.HasManyAssociation.html" class="definedIn docClass">Ext.data.HasManyAssociation</a><br/><a href="../source/HasManyAssociation.html#Ext-data.HasManyAssociation-cfg-type" class="viewSource">view source</a></div><a name="type"></a><a name="config-type"></a><a href="Ext.data.HasManyAssociation.html#" rel="config-type" class="cls expand">type</a><span> : String</span></div><div class="description"><div class="short">The type configuration can be used when creating associations using a configuration object.
 234 Use 'hasMany' to create a...</div><div class="long"><p>The type configuration can be used when creating associations using a configuration object.
 235 Use 'hasMany' to create a HasManyAssocation</p>
 236
 237 <pre><code>associations: [{
 238     type: 'hasMany',
 239     model: 'User'
 240 }]
 241 </code></pre>
 242
 243 </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-associatedName" class="member f inherited"><a href="Ext.data.HasManyAssociation.html#property-associatedName" rel="property-associatedName" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-property-associatedName" class="viewSource">view source</a></div><a name="associatedName"></a><a name="property-associatedName"></a><a href="Ext.data.HasManyAssociation.html#" rel="property-associatedName" class="cls expand">associatedName</a><span> : String</span></div><div class="description"><div class="short"><p>The name of the model is on the other end of the association (e.g. if a User model hasMany Orders, this is 'Order')</p>
 244 </div><div class="long"><p>The name of the model is on the other end of the association (e.g. if a User model hasMany Orders, this is 'Order')</p>
 245 </div></div></div><div id="property-ownerName" class="member inherited"><a href="Ext.data.HasManyAssociation.html#property-ownerName" rel="property-ownerName" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-property-ownerName" class="viewSource">view source</a></div><a name="ownerName"></a><a name="property-ownerName"></a><a href="Ext.data.HasManyAssociation.html#" rel="property-ownerName" class="cls expand">ownerName</a><span> : String</span></div><div class="description"><div class="short"><p>The name of the model that 'owns' the association</p>
 246 </div><div class="long"><p>The name of the model that 'owns' the association</p>
 247 </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-HasManyAssociation" class="member f inherited"><a href="Ext.data.HasManyAssociation.html#method-HasManyAssociation" rel="method-HasManyAssociation" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-method-constructor" class="viewSource">view source</a></div><a name="HasManyAssociation"></a><a name="method-HasManyAssociation"></a><a href="Ext.data.HasManyAssociation.html#" rel="method-HasManyAssociation" class="cls expand">HasManyAssociation</a>(
 248 <span class="pre">Object config</span>)
 249  : void</div><div class="description"><div class="short"><p>&nbsp;</p></div><div class="long">
 250 <h3 class="pa">Parameters</h3><ul><li><span class="pre">config</span> : Object<div class="sub-desc"><p>Optional config object</p>
 251 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
 252 </li></ul></div></div></div><div id="method-getReader" class="member inherited"><a href="Ext.data.HasManyAssociation.html#method-getReader" rel="method-getReader" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.Association.html" class="definedIn docClass">Ext.data.Association</a><br/><a href="../source/Association.html#Ext-data.Association-method-getReader" class="viewSource">view source</a></div><a name="getReader"></a><a name="method-getReader"></a><a href="Ext.data.HasManyAssociation.html#" rel="method-getReader" class="cls expand">getReader</a> : Ext.data.reader.Reader</div><div class="description"><div class="short"><p>Get a specialized reader for reading associated data</p>
 253 </div><div class="long"><p>Get a specialized reader for reading associated data</p>
 254 <h3 class="pa">Returns</h3><ul><li><span class="pre">Ext.data.reader.Reader</span>&nbsp; &nbsp;<p>The reader, null if not supplied</p>
 255 </li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>