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">
12 origDocClass: 'Ext.data.BelongsToAssociation',
13 docClass: 'Ext.data.BelongsToAssociation',
14 docReq: 'Ext.data.BelongsToAssociation',
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');
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>
43 <pre class="prettyprint"><code>Ext.define('Category', {
44 extend: 'Ext.data.Model',
46 {name: 'id', type: 'int'},
47 {name: 'name', type: 'string'}
51 Ext.define('Product', {
52 extend: 'Ext.data.Model',
54 {name: 'id', type: 'int'},
55 {name: 'category_id', type: 'int'},
56 {name: 'name', type: 'string'}
58 // we can use the belongsTo shortcut on the model to create a belongsTo association
59 belongsTo: {type: 'belongsTo', model: 'Category'}
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>
71 <p><u>Generated getter function</u></p>
76 <p>The first function that is added to the owner model is a getter function:</p>
81 <pre class="prettyprint"><code>var product = new Product({
87 product.getCategory(function(category, operation) {
88 //do something with the category object
89 alert(category.get('id')); //alerts 20
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>
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>
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
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>
128 <p><u>Generated setter function</u></p>
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>
139 <pre class="prettyprint"><code>//this call
140 product.setCategory(10);
142 //is equivalent to this call:
143 product.set('category_id', 10);
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>
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
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
168 <p><u>Customisation</u></p>
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>
179 <pre class="prettyprint"><code>Ext.define('Product', {
183 {type: 'belongsTo', model: 'Category', primaryKey: 'unique_id', foreignKey: 'cat_id'}
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>
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> </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> </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> </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>
205 <pre><code>Ext.define('Order', {
206 extend: 'Ext.data.Model',
207 fields: ['id', 'date'],
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
216 var product = new Product({
221 product.getOrder(); // Will make a call to the server asking for order_id 22
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> </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> </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> </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> </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> </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> </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>
242 <pre><code>associations: [{
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> </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> </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> </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> </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>
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> </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> <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>