Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / BelongsToAssociation.html
index 2849fa9..15d6315 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
  * @class Ext.data.BelongsToAssociation
  * @extends Ext.data.Association
  *
- * &lt;p&gt;Represents a many to one association with another model. The owner model is expected to have
- * a foreign key which references the primary key of the associated model:&lt;/p&gt;
+ * Represents a many to one association with another model. The owner model is expected to have
+ * a foreign key which references the primary key of the associated model:
  *
-&lt;pre&gt;&lt;code&gt;
-Ext.define('Category', {
-    extend: 'Ext.data.Model',
-    fields: [
-        {name: 'id',   type: 'int'},
-        {name: 'name', type: 'string'}
-    ]
-});
-
-Ext.define('Product', {
-    extend: 'Ext.data.Model',
-    fields: [
-        {name: 'id',          type: 'int'},
-        {name: 'category_id', type: 'int'},
-        {name: 'name',        type: 'string'}
-    ],
-    // we can use the belongsTo shortcut on the model to create a belongsTo association
-    belongsTo: {type: 'belongsTo', model: 'Category'}
-});
-&lt;/code&gt;&lt;/pre&gt;
- * &lt;p&gt;In the example above we have created models for Products and Categories, and linked them together
+ *     Ext.define('Category', {
+ *         extend: 'Ext.data.Model',
+ *         fields: [
+ *             { name: 'id',   type: 'int' },
+ *             { name: 'name', type: 'string' }
+ *         ]
+ *     });
+ *
+ *     Ext.define('Product', {
+ *         extend: 'Ext.data.Model',
+ *         fields: [
+ *             { name: 'id',          type: 'int' },
+ *             { name: 'category_id', type: 'int' },
+ *             { name: 'name',        type: 'string' }
+ *         ],
+ *         // we can use the belongsTo shortcut on the model to create a belongsTo association
+ *         associations: [
+ *             { type: 'belongsTo', model: 'Category' }
+ *         ]
+ *     });
+ *
+ * In the example above we have created models for Products and Categories, and linked them together
  * by saying that each Product belongs to a Category. This automatically links each Product to a Category
- * based on the Product's category_id, and provides new functions on the Product model:&lt;/p&gt;
+ * based on the Product's category_id, and provides new functions on the Product model:
  *
- * &lt;p&gt;&lt;u&gt;Generated getter function&lt;/u&gt;&lt;/p&gt;
+ * ## Generated getter function
  *
- * &lt;p&gt;The first function that is added to the owner model is a getter function:&lt;/p&gt;
+ * The first function that is added to the owner model is a getter function:
  *
-&lt;pre&gt;&lt;code&gt;
-var product = new Product({
-    id: 100,
-    category_id: 20,
-    name: 'Sneakers'
-});
-
-product.getCategory(function(category, operation) {
-    //do something with the category object
-    alert(category.get('id')); //alerts 20
-}, this);
-&lt;/code&gt;&lt;/pre&gt;
-*
- * &lt;p&gt;The getCategory function was created on the Product model when we defined the association. This uses the
+ *     var product = new Product({
+ *         id: 100,
+ *         category_id: 20,
+ *         name: 'Sneakers'
+ *     });
+ *
+ *     product.getCategory(function(category, operation) {
+ *         // do something with the category object
+ *         alert(category.get('id')); // alerts 20
+ *     }, this);
+ *
+ * The getCategory function was created on the Product model when we defined the association. This uses the
  * Category's configured {@link Ext.data.proxy.Proxy proxy} to load the Category asynchronously, calling the provided
- * callback when it has loaded.&lt;/p&gt;
+ * callback when it has loaded.
  *
- * &lt;p&gt;The new getCategory function will also accept an object containing success, failure and callback properties
+ * The new getCategory function will also accept an object containing success, failure and callback properties
  * - callback will always be called, success will only be called if the associated model was loaded successfully
- * and failure will only be called if the associatied model could not be loaded:&lt;/p&gt;
+ * and failure will only be called if the associatied model could not be loaded:
  *
-&lt;pre&gt;&lt;code&gt;
-product.getCategory({
-    callback: function(category, operation) {}, //a function that will always be called
-    success : function(category, operation) {}, //a function that will only be called if the load succeeded
-    failure : function(category, operation) {}, //a function that will only be called if the load did not succeed
-    scope   : this //optionally pass in a scope object to execute the callbacks in
-});
-&lt;/code&gt;&lt;/pre&gt;
+ *     product.getCategory({
+ *         callback: function(category, operation) {}, // a function that will always be called
+ *         success : function(category, operation) {}, // a function that will only be called if the load succeeded
+ *         failure : function(category, operation) {}, // a function that will only be called if the load did not succeed
+ *         scope   : this // optionally pass in a scope object to execute the callbacks in
+ *     });
  *
- * &lt;p&gt;In each case above the callbacks are called with two arguments - the associated model instance and the
+ * In each case above the callbacks are called with two arguments - the associated model instance and the
  * {@link Ext.data.Operation operation} object that was executed to load that instance. The Operation object is
- * useful when the instance could not be loaded.&lt;/p&gt;
+ * useful when the instance could not be loaded.
  *
- * &lt;p&gt;&lt;u&gt;Generated setter function&lt;/u&gt;&lt;/p&gt;
+ * ## Generated setter function
  *
- * &lt;p&gt;The second generated function sets the associated model instance - if only a single argument is passed to
- * the setter then the following two calls are identical:&lt;/p&gt;
+ * The second generated function sets the associated model instance - if only a single argument is passed to
+ * the setter then the following two calls are identical:
  *
-&lt;pre&gt;&lt;code&gt;
-//this call
-product.setCategory(10);
-
-//is equivalent to this call:
-product.set('category_id', 10);
-&lt;/code&gt;&lt;/pre&gt;
- * &lt;p&gt;If we pass in a second argument, the model will be automatically saved and the second argument passed to
- * the owner model's {@link Ext.data.Model#save save} method:&lt;/p&gt;
-&lt;pre&gt;&lt;code&gt;
-product.setCategory(10, function(product, operation) {
-    //the product has been saved
-    alert(product.get('category_id')); //now alerts 10
-});
-
-//alternative syntax:
-product.setCategory(10, {
-    callback: function(product, operation), //a function that will always be called
-    success : function(product, operation), //a function that will only be called if the load succeeded
-    failure : function(product, operation), //a function that will only be called if the load did not succeed
-    scope   : this //optionally pass in a scope object to execute the callbacks in
-})
-&lt;/code&gt;&lt;/pre&gt;
-*
- * &lt;p&gt;&lt;u&gt;Customisation&lt;/u&gt;&lt;/p&gt;
+ *     // this call...
+ *     product.setCategory(10);
  *
- * &lt;p&gt;Associations reflect on the models they are linking to automatically set up properties such as the
- * {@link #primaryKey} and {@link #foreignKey}. These can alternatively be specified:&lt;/p&gt;
+ *     // is equivalent to this call:
+ *     product.set('category_id', 10);
  *
-&lt;pre&gt;&lt;code&gt;
-Ext.define('Product', {
-    fields: [...],
-
-    associations: [
-        {type: 'belongsTo', model: 'Category', primaryKey: 'unique_id', foreignKey: 'cat_id'}
-    ]
-});
- &lt;/code&gt;&lt;/pre&gt;
+ * If we pass in a second argument, the model will be automatically saved and the second argument passed to
+ * the owner model's {@link Ext.data.Model#save save} method:
+ *
+ *     product.setCategory(10, function(product, operation) {
+ *         // the product has been saved
+ *         alert(product.get('category_id')); //now alerts 10
+ *     });
+ *
+ *     //alternative syntax:
+ *     product.setCategory(10, {
+ *         callback: function(product, operation), // a function that will always be called
+ *         success : function(product, operation), // a function that will only be called if the load succeeded
+ *         failure : function(product, operation), // a function that will only be called if the load did not succeed
+ *         scope   : this //optionally pass in a scope object to execute the callbacks in
+ *     })
+ *
+ * ## Customisation
+ *
+ * Associations reflect on the models they are linking to automatically set up properties such as the
+ * {@link #primaryKey} and {@link #foreignKey}. These can alternatively be specified:
+ *
+ *     Ext.define('Product', {
+ *         fields: [...],
+ *
+ *         associations: [
+ *             { type: 'belongsTo', model: 'Category', primaryKey: 'unique_id', foreignKey: 'cat_id' }
+ *         ]
+ *     });
  *
- * &lt;p&gt;Here we replaced the default primary key (defaults to 'id') and foreign key (calculated as 'category_id')
- * with our own settings. Usually this will not be needed.&lt;/p&gt;
+ * Here we replaced the default primary key (defaults to 'id') and foreign key (calculated as 'category_id')
+ * with our own settings. Usually this will not be needed.
  */
 Ext.define('Ext.data.BelongsToAssociation', {
     extend: 'Ext.data.Association',
@@ -141,26 +134,25 @@ Ext.define('Ext.data.BelongsToAssociation', {
 </span>     * @cfg {String} foreignKey The name of the foreign key on the owner model that links it to the associated
      * model. Defaults to the lowercased name of the associated model plus &quot;_id&quot;, e.g. an association with a
      * model called Product would set up a product_id foreign key.
-     * &lt;pre&gt;&lt;code&gt;
-Ext.define('Order', {
-    extend: 'Ext.data.Model',
-    fields: ['id', 'date'],
-    hasMany: 'Product'
-});
-
-Ext.define('Product', {
-    extend: 'Ext.data.Model',
-    fields: ['id', 'name', 'order_id'], // refers to the id of the order that this product belongs to
-    belongsTo: 'Group'
-});
-var product = new Product({
-    id: 1,
-    name: 'Product 1',
-    order_id: 22
-}, 1);
-product.getOrder(); // Will make a call to the server asking for order_id 22
-
-     * &lt;/code&gt;&lt;/pre&gt;
+     *
+     *     Ext.define('Order', {
+     *         extend: 'Ext.data.Model',
+     *         fields: ['id', 'date'],
+     *         hasMany: 'Product'
+     *     });
+     *
+     *     Ext.define('Product', {
+     *         extend: 'Ext.data.Model',
+     *         fields: ['id', 'name', 'order_id'], // refers to the id of the order that this product belongs to
+     *         belongsTo: 'Group'
+     *     });
+     *     var product = new Product({
+     *         id: 1,
+     *         name: 'Product 1',
+     *         order_id: 22
+     *     }, 1);
+     *     product.getOrder(); // Will make a call to the server asking for order_id 22
+     *
      */
 
 <span id='Ext-data-BelongsToAssociation-cfg-getterName'>    /**
@@ -172,18 +164,16 @@ product.getOrder(); // Will make a call to the server asking for order_id 22
 </span>     * @cfg {String} setterName The name of the setter function that will be added to the local model's prototype.
      * Defaults to 'set' + the name of the foreign model, e.g. setCategory
      */
-    
+
 <span id='Ext-data-BelongsToAssociation-cfg-type'>    /**
 </span>     * @cfg {String} type The type configuration can be used when creating associations using a configuration object.
      * Use 'belongsTo' to create a HasManyAssocation
-     * &lt;pre&gt;&lt;code&gt;
-associations: [{
-    type: 'belongsTo',
-    model: 'User'
-}]
-     * &lt;/code&gt;&lt;/pre&gt;
+     *
+     *     associations: [{
+     *         type: 'belongsTo',
+     *         model: 'User'
+     *     }]
      */
-
     constructor: function(config) {
         this.callParent(arguments);
 
@@ -275,7 +265,7 @@ associations: [{
                 instance = model[instanceName];
                 args = [instance];
                 scope = scope || model;
-                
+
                 //TODO: We're duplicating the callback invokation code that the instance.load() call above
                 //makes here - ought to be able to normalize this - perhaps by caching at the Model.load layer
                 //instead of the association layer.