Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / docs / source / HasManyAssociation.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-HasManyAssociation'>/**
19 </span> * @author Ed Spencer
20  * @class Ext.data.HasManyAssociation
21  * @extends Ext.data.Association
22  * 
23  * &lt;p&gt;Represents a one-to-many relationship between two models. Usually created indirectly via a model definition:&lt;/p&gt;
24  * 
25 &lt;pre&gt;&lt;code&gt;
26 Ext.define('Product', {
27     extend: 'Ext.data.Model',
28     fields: [
29         {name: 'id',      type: 'int'},
30         {name: 'user_id', type: 'int'},
31         {name: 'name',    type: 'string'}
32     ]
33 });
34
35 Ext.define('User', {
36     extend: 'Ext.data.Model',
37     fields: [
38         {name: 'id',   type: 'int'},
39         {name: 'name', type: 'string'}
40     ],
41     // we can use the hasMany shortcut on the model to create a hasMany association
42     hasMany: {model: 'Product', name: 'products'}
43 });
44 &lt;/pre&gt;&lt;/code&gt;
45
46  * &lt;p&gt;Above we created Product and User models, and linked them by saying that a User hasMany Products. This gives
47  * us a new function on every User instance, in this case the function is called 'products' because that is the name
48  * we specified in the association configuration above.&lt;/p&gt;
49  * 
50  * &lt;p&gt;This new function returns a specialized {@link Ext.data.Store Store} which is automatically filtered to load
51  * only Products for the given model instance:&lt;/p&gt;
52  * 
53 &lt;pre&gt;&lt;code&gt;
54 //first, we load up a User with id of 1
55 var user = Ext.ModelManager.create({id: 1, name: 'Ed'}, 'User');
56
57 //the user.products function was created automatically by the association and returns a {@link Ext.data.Store Store}
58 //the created store is automatically scoped to the set of Products for the User with id of 1
59 var products = user.products();
60
61 //we still have all of the usual Store functions, for example it's easy to add a Product for this User
62 products.add({
63     name: 'Another Product'
64 });
65
66 //saves the changes to the store - this automatically sets the new Product's user_id to 1 before saving
67 products.sync();
68 &lt;/code&gt;&lt;/pre&gt;
69  * 
70  * &lt;p&gt;The new Store is only instantiated the first time you call products() to conserve memory and processing time,
71  * though calling products() a second time returns the same store instance.&lt;/p&gt;
72  * 
73  * &lt;p&gt;&lt;u&gt;Custom filtering&lt;/u&gt;&lt;/p&gt;
74  * 
75  * &lt;p&gt;The Store is automatically furnished with a filter - by default this filter tells the store to only return
76  * records where the associated model's foreign key matches the owner model's primary key. For example, if a User
77  * with ID = 100 hasMany Products, the filter loads only Products with user_id == 100.&lt;/p&gt;
78  * 
79  * &lt;p&gt;Sometimes we want to filter by another field - for example in the case of a Twitter search application we may
80  * have models for Search and Tweet:&lt;/p&gt;
81  * 
82 &lt;pre&gt;&lt;code&gt;
83 Ext.define('Search', {
84     extend: 'Ext.data.Model',
85     fields: [
86         'id', 'query'
87     ],
88
89     hasMany: {
90         model: 'Tweet',
91         name : 'tweets',
92         filterProperty: 'query'
93     }
94 });
95
96 Ext.define('Tweet', {
97     extend: 'Ext.data.Model',
98     fields: [
99         'id', 'text', 'from_user'
100     ]
101 });
102
103 //returns a Store filtered by the filterProperty
104 var store = new Search({query: 'Sencha Touch'}).tweets();
105 &lt;/code&gt;&lt;/pre&gt;
106  * 
107  * &lt;p&gt;The tweets association above is filtered by the query property by setting the {@link #filterProperty}, and is
108  * equivalent to this:&lt;/p&gt;
109  * 
110 &lt;pre&gt;&lt;code&gt;
111 var store = new Ext.data.Store({
112     model: 'Tweet',
113     filters: [
114         {
115             property: 'query',
116             value   : 'Sencha Touch'
117         }
118     ]
119 });
120 &lt;/code&gt;&lt;/pre&gt;
121  */
122 Ext.define('Ext.data.HasManyAssociation', {
123     extend: 'Ext.data.Association',
124     requires: ['Ext.util.Inflector'],
125
126     alias: 'association.hasmany',
127
128 <span id='Ext-data-HasManyAssociation-cfg-foreignKey'>    /**
129 </span>     * @cfg {String} foreignKey The name of the foreign key on the associated model that links it to the owner
130      * model. Defaults to the lowercased name of the owner model plus &quot;_id&quot;, e.g. an association with a where a
131      * model called Group hasMany Users would create 'group_id' as the foreign key. When the remote store is loaded,
132      * the store is automatically filtered so that only records with a matching foreign key are included in the 
133      * resulting child store. This can be overridden by specifying the {@link #filterProperty}.
134      * &lt;pre&gt;&lt;code&gt;
135 Ext.define('Group', {
136     extend: 'Ext.data.Model',
137     fields: ['id', 'name'],
138     hasMany: 'User'
139 });
140
141 Ext.define('User', {
142     extend: 'Ext.data.Model',
143     fields: ['id', 'name', 'group_id'], // refers to the id of the group that this user belongs to
144     belongsTo: 'Group'
145 });
146      * &lt;/code&gt;&lt;/pre&gt;
147      */
148     
149 <span id='Ext-data-HasManyAssociation-cfg-name'>    /**
150 </span>     * @cfg {String} name The name of the function to create on the owner model to retrieve the child store.
151      * If not specified, the pluralized name of the child model is used.
152      * &lt;pre&gt;&lt;code&gt;
153 // This will create a users() method on any Group model instance
154 Ext.define('Group', {
155     extend: 'Ext.data.Model',
156     fields: ['id', 'name'],
157     hasMany: 'User'
158 });
159 var group = new Group();
160 console.log(group.users());
161
162 // The method to retrieve the users will now be getUserList
163 Ext.define('Group', {
164     extend: 'Ext.data.Model',
165     fields: ['id', 'name'],
166     hasMany: {model: 'User', name: 'getUserList'}
167 });
168 var group = new Group();
169 console.log(group.getUserList());
170      * &lt;/code&gt;&lt;/pre&gt;
171      */
172     
173 <span id='Ext-data-HasManyAssociation-cfg-storeConfig'>    /**
174 </span>     * @cfg {Object} storeConfig Optional configuration object that will be passed to the generated Store. Defaults to 
175      * undefined.
176      */
177     
178 <span id='Ext-data-HasManyAssociation-cfg-filterProperty'>    /**
179 </span>     * @cfg {String} filterProperty Optionally overrides the default filter that is set up on the associated Store. If
180      * this is not set, a filter is automatically created which filters the association based on the configured 
181      * {@link #foreignKey}. See intro docs for more details. Defaults to undefined
182      */
183     
184 <span id='Ext-data-HasManyAssociation-cfg-autoLoad'>    /**
185 </span>     * @cfg {Boolean} autoLoad True to automatically load the related store from a remote source when instantiated.
186      * Defaults to &lt;tt&gt;false&lt;/tt&gt;.
187      */
188     
189 <span id='Ext-data-HasManyAssociation-cfg-type'>    /**
190 </span>     * @cfg {String} type The type configuration can be used when creating associations using a configuration object.
191      * Use 'hasMany' to create a HasManyAssocation
192      * &lt;pre&gt;&lt;code&gt;
193 associations: [{
194     type: 'hasMany',
195     model: 'User'
196 }]
197      * &lt;/code&gt;&lt;/pre&gt;
198      */
199     
200     constructor: function(config) {
201         var me = this,
202             ownerProto,
203             name;
204             
205         me.callParent(arguments);
206         
207         me.name = me.name || Ext.util.Inflector.pluralize(me.associatedName.toLowerCase());
208         
209         ownerProto = me.ownerModel.prototype;
210         name = me.name;
211         
212         Ext.applyIf(me, {
213             storeName : name + &quot;Store&quot;,
214             foreignKey: me.ownerName.toLowerCase() + &quot;_id&quot;
215         });
216         
217         ownerProto[name] = me.createStore();
218     },
219     
220 <span id='Ext-data-HasManyAssociation-method-createStore'>    /**
221 </span>     * @private
222      * Creates a function that returns an Ext.data.Store which is configured to load a set of data filtered
223      * by the owner model's primary key - e.g. in a hasMany association where Group hasMany Users, this function
224      * returns a Store configured to return the filtered set of a single Group's Users.
225      * @return {Function} The store-generating function
226      */
227     createStore: function() {
228         var that            = this,
229             associatedModel = that.associatedModel,
230             storeName       = that.storeName,
231             foreignKey      = that.foreignKey,
232             primaryKey      = that.primaryKey,
233             filterProperty  = that.filterProperty,
234             autoLoad        = that.autoLoad,
235             storeConfig     = that.storeConfig || {};
236         
237         return function() {
238             var me = this,
239                 config, filter,
240                 modelDefaults = {};
241                 
242             if (me[storeName] === undefined) {
243                 if (filterProperty) {
244                     filter = {
245                         property  : filterProperty,
246                         value     : me.get(filterProperty),
247                         exactMatch: true
248                     };
249                 } else {
250                     filter = {
251                         property  : foreignKey,
252                         value     : me.get(primaryKey),
253                         exactMatch: true
254                     };
255                 }
256                 
257                 modelDefaults[foreignKey] = me.get(primaryKey);
258                 
259                 config = Ext.apply({}, storeConfig, {
260                     model        : associatedModel,
261                     filters      : [filter],
262                     remoteFilter : false,
263                     modelDefaults: modelDefaults
264                 });
265                 
266                 me[storeName] = Ext.create('Ext.data.Store', config);
267                 if (autoLoad) {
268                     me[storeName].load();
269                 }
270             }
271             
272             return me[storeName];
273         };
274     },
275     
276 <span id='Ext-data-HasManyAssociation-method-read'>    /**
277 </span>     * Read associated data
278      * @private
279      * @param {Ext.data.Model} record The record we're writing to
280      * @param {Ext.data.reader.Reader} reader The reader for the associated model
281      * @param {Object} associationData The raw associated data
282      */
283     read: function(record, reader, associationData){
284         var store = record[this.name](),
285             inverse;
286     
287         store.add(reader.read(associationData).records);
288     
289         //now that we've added the related records to the hasMany association, set the inverse belongsTo
290         //association on each of them if it exists
291         inverse = this.associatedModel.prototype.associations.findBy(function(assoc){
292             return assoc.type === 'belongsTo' &amp;&amp; assoc.associatedName === record.$className;
293         });
294     
295         //if the inverse association was found, set it now on each record we've just created
296         if (inverse) {
297             store.data.each(function(associatedRecord){
298                 associatedRecord[inverse.instanceName] = record;
299             });
300         }
301     }
302 });</pre>
303 </body>
304 </html>