Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / api / Ext.data.BelongsToAssociation.html
1 <!DOCTYPE html><html><head><title>Ext.data.BelongsToAssociation | 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.BelongsToAssociation',
13         docClass: 'Ext.data.BelongsToAssociation',
14         docReq: 'Ext.data.BelongsToAssociation',
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 = 'BelongsToAssociation.html#Ext-data.BelongsToAssociation';
33     clsInfo = {"methods":["BelongsToAssociation","getReader"],"cfgs":["associatedModel","associationKey","foreignKey","getterName","ownerModel","primaryKey","reader","setterName","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/BelongsToAssociation.html#Ext-data.BelongsToAssociation" target="_blank">Ext.data.BelongsToAssociation</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.BelongsToAssociation</strong></div></div></pre><p>Represents a many to one association with another model. The owner model is expected to have
38 a foreign key which references the primary key of the associated model:</p>
39
40
41
42
43 <pre class="prettyprint"><code>Ext.define('Category', {
44     extend: 'Ext.data.Model',
45     fields: [
46         {name: 'id',   type: 'int'},
47         {name: 'name', type: 'string'}
48     ]
49 });
50
51 Ext.define('Product', {
52     extend: 'Ext.data.Model',
53     fields: [
54         {name: 'id',          type: 'int'},
55         {name: 'category_id', type: 'int'},
56         {name: 'name',        type: 'string'}
57     ],
58     // we can use the belongsTo shortcut on the model to create a belongsTo association
59     belongsTo: {type: 'belongsTo', model: 'Category'}
60 });
61 </code></pre>
62
63
64 <p>In the example above we have created models for Products and Categories, and linked them together
65 by saying that each Product belongs to a Category. This automatically links each Product to a Category
66 based on the Product's category_id, and provides new functions on the Product model:</p>
67
68
69
70
71 <p><u>Generated getter function</u></p>
72
73
74
75
76 <p>The first function that is added to the owner model is a getter function:</p>
77
78
79
80
81 <pre class="prettyprint"><code>var product = new Product({
82     id: 100,
83     category_id: 20,
84     name: 'Sneakers'
85 });
86
87 product.getCategory(function(category, operation) {
88     //do something with the category object
89     alert(category.get('id')); //alerts 20
90 }, this);
91 </code></pre>
92
93
94
95
96 <p>The getCategory function was created on the Product model when we defined the association. This uses the
97 Category's configured <a href="Ext.data.proxy.Proxy.html" rel="Ext.data.proxy.Proxy" class="docClass">proxy</a> to load the Category asynchronously, calling the provided
98 callback when it has loaded.</p>
99
100
101
102
103 <p>The new getCategory function will also accept an object containing success, failure and callback properties
104 - callback will always be called, success will only be called if the associated model was loaded successfully
105 and failure will only be called if the associatied model could not be loaded:</p>
106
107
108
109
110 <pre class="prettyprint"><code>product.getCategory({
111     callback: function(category, operation) {}, //a function that will always be called
112     success : function(category, operation) {}, //a function that will only be called if the load succeeded
113     failure : function(category, operation) {}, //a function that will only be called if the load did not succeed
114     scope   : this //optionally pass in a scope object to execute the callbacks in
115 });
116 </code></pre>
117
118
119
120
121 <p>In each case above the callbacks are called with two arguments - the associated model instance and the
122 <a href="Ext.data.Operation.html" rel="Ext.data.Operation" class="docClass">operation</a> object that was executed to load that instance. The Operation object is
123 useful when the instance could not be loaded.</p>
124
125
126
127
128 <p><u>Generated setter function</u></p>
129
130
131
132
133 <p>The second generated function sets the associated model instance - if only a single argument is passed to
134 the setter then the following two calls are identical:</p>
135
136
137
138
139 <pre class="prettyprint"><code>//this call
140 product.setCategory(10);
141
142 //is equivalent to this call:
143 product.set('category_id', 10);
144 </code></pre>
145
146
147 <p>If we pass in a second argument, the model will be automatically saved and the second argument passed to
148 the owner model's <a href="Ext.data.Model.html#save" rel="Ext.data.Model#save" class="docClass">save</a> method:</p>
149
150
151 <pre class="prettyprint"><code>product.setCategory(10, function(product, operation) {
152     //the product has been saved
153     alert(product.get('category_id')); //now alerts 10
154 });
155
156 //alternative syntax:
157 product.setCategory(10, {
158     callback: function(product, operation), //a function that will always be called
159     success : function(product, operation), //a function that will only be called if the load succeeded
160     failure : function(product, operation), //a function that will only be called if the load did not succeed
161     scope   : this //optionally pass in a scope object to execute the callbacks in
162 })
163 </code></pre>
164
165
166
167
168 <p><u>Customisation</u></p>
169
170
171
172
173 <p>Associations reflect on the models they are linking to automatically set up properties such as the
174 <a href="Ext.data.BelongsToAssociation.html#primaryKey" rel="Ext.data.BelongsToAssociation#primaryKey" class="docClass">primaryKey</a> and <a href="Ext.data.BelongsToAssociation.html#foreignKey" rel="Ext.data.BelongsToAssociation#foreignKey" class="docClass">foreignKey</a>. These can alternatively be specified:</p>
175
176
177
178
179 <pre class="prettyprint"><code>Ext.define('Product', {
180     fields: [...],
181
182     associations: [
183         {type: 'belongsTo', model: 'Category', primaryKey: 'unique_id', foreignKey: 'cat_id'}
184     ]
185 });
186  </code></pre>
187
188
189
190
191 <p>Here we replaced the default primary key (defaults to 'id') and foreign key (calculated as 'category_id')
192 with our own settings. Usually this will not be needed.</p>
193
194 <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.BelongsToAssociation.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.BelongsToAssociation.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>
195 </div><div class="long"><p>The string name of the model that is being associated with. Required</p>
196 </div></div></div><div id="config-associationKey" class="member inherited"><a href="Ext.data.BelongsToAssociation.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.BelongsToAssociation.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.
197 Defaults to the name of the associated model.</p>
198 </div><div class="long"><p>The name of the property in the data to read the association from.
199 Defaults to the name of the associated model.</p>
200 </div></div></div><div id="config-foreignKey" class="member ni"><a href="Ext.data.BelongsToAssociation.html#config-foreignKey" rel="config-foreignKey" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.BelongsToAssociation.html" class="definedIn docClass">Ext.data.BelongsToAssociation</a><br/><a href="../source/BelongsToAssociation.html#Ext-data.BelongsToAssociation-cfg-foreignKey" class="viewSource">view source</a></div><a name="foreignKey"></a><a name="config-foreignKey"></a><a href="Ext.data.BelongsToAssociation.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 owner model that links it to the associated
201 model. Defaults to the lowercased name...</div><div class="long"><p>The name of the foreign key on the owner model that links it to the associated
202 model. Defaults to the lowercased name of the associated model plus "_id", e.g. an association with a
203 model called Product would set up a product_id foreign key.</p>
204
205 <pre><code>Ext.define('Order', {
206     extend: 'Ext.data.Model',
207     fields: ['id', 'date'],
208     hasMany: 'Product'
209 });
210
211 Ext.define('Product', {
212     extend: 'Ext.data.Model',
213     fields: ['id', 'name', 'order_id'], // refers to the id of the order that this product belongs to
214     belongsTo: 'Group'
215 });
216 var product = new Product({
217     id: 1,
218     name: 'Product 1',
219     order_id: 22
220 }, 1);
221 product.getOrder(); // Will make a call to the server asking for order_id 22
222
223 </code></pre>
224
225 </div></div></div><div id="config-getterName" class="member ni"><a href="Ext.data.BelongsToAssociation.html#config-getterName" rel="config-getterName" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.BelongsToAssociation.html" class="definedIn docClass">Ext.data.BelongsToAssociation</a><br/><a href="../source/BelongsToAssociation.html#Ext-data.BelongsToAssociation-cfg-getterName" class="viewSource">view source</a></div><a name="getterName"></a><a name="config-getterName"></a><a href="Ext.data.BelongsToAssociation.html#" rel="config-getterName" class="cls expand">getterName</a><span> : String</span></div><div class="description"><div class="short">The name of the getter function that will be added to the local model's prototype.
226 Defaults to 'get' + the name of th...</div><div class="long"><p>The name of the getter function that will be added to the local model's prototype.
227 Defaults to 'get' + the name of the foreign model, e.g. getCategory</p>
228 </div></div></div><div id="config-ownerModel" class="member inherited"><a href="Ext.data.BelongsToAssociation.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.BelongsToAssociation.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>
229 </div><div class="long"><p>The string name of the model that owns the association. Required</p>
230 </div></div></div><div id="config-primaryKey" class="member inherited"><a href="Ext.data.BelongsToAssociation.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.BelongsToAssociation.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'.
231 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'.
232 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>
233 </div></div></div><div id="config-reader" class="member inherited"><a href="Ext.data.BelongsToAssociation.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.BelongsToAssociation.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>
234 </div><div class="long"><p>A special reader to read associated data</p>
235 </div></div></div><div id="config-setterName" class="member ni"><a href="Ext.data.BelongsToAssociation.html#config-setterName" rel="config-setterName" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.BelongsToAssociation.html" class="definedIn docClass">Ext.data.BelongsToAssociation</a><br/><a href="../source/BelongsToAssociation.html#Ext-data.BelongsToAssociation-cfg-setterName" class="viewSource">view source</a></div><a name="setterName"></a><a name="config-setterName"></a><a href="Ext.data.BelongsToAssociation.html#" rel="config-setterName" class="cls expand">setterName</a><span> : String</span></div><div class="description"><div class="short">The name of the setter function that will be added to the local model's prototype.
236 Defaults to 'set' + the name of th...</div><div class="long"><p>The name of the setter function that will be added to the local model's prototype.
237 Defaults to 'set' + the name of the foreign model, e.g. setCategory</p>
238 </div></div></div><div id="config-type" class="member ni"><a href="Ext.data.BelongsToAssociation.html#config-type" rel="config-type" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.data.BelongsToAssociation.html" class="definedIn docClass">Ext.data.BelongsToAssociation</a><br/><a href="../source/BelongsToAssociation.html#Ext-data.BelongsToAssociation-cfg-type" class="viewSource">view source</a></div><a name="type"></a><a name="config-type"></a><a href="Ext.data.BelongsToAssociation.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.
239 Use 'belongsTo' to create...</div><div class="long"><p>The type configuration can be used when creating associations using a configuration object.
240 Use 'belongsTo' to create a HasManyAssocation</p>
241
242 <pre><code>associations: [{
243     type: 'belongsTo',
244     model: 'User'
245 }]
246 </code></pre>
247
248 </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.BelongsToAssociation.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.BelongsToAssociation.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>
249 </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>
250 </div></div></div><div id="property-ownerName" class="member inherited"><a href="Ext.data.BelongsToAssociation.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.BelongsToAssociation.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>
251 </div><div class="long"><p>The name of the model that 'owns' the association</p>
252 </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-BelongsToAssociation" class="member f inherited"><a href="Ext.data.BelongsToAssociation.html#method-BelongsToAssociation" rel="method-BelongsToAssociation" 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="BelongsToAssociation"></a><a name="method-BelongsToAssociation"></a><a href="Ext.data.BelongsToAssociation.html#" rel="method-BelongsToAssociation" class="cls expand">BelongsToAssociation</a>(
253 <span class="pre">Object config</span>)
254  : void</div><div class="description"><div class="short"><p>&nbsp;</p></div><div class="long">
255 <h3 class="pa">Parameters</h3><ul><li><span class="pre">config</span> : Object<div class="sub-desc"><p>Optional config object</p>
256 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
257 </li></ul></div></div></div><div id="method-getReader" class="member inherited"><a href="Ext.data.BelongsToAssociation.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.BelongsToAssociation.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>
258 </div><div class="long"><p>Get a specialized reader for reading associated data</p>
259 <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>
260 </li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>