docs/source/BelongsToAssociation.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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/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-BelongsToAssociation'>/**
  19 </span> * @author Ed Spencer
  20  * @class Ext.data.BelongsToAssociation
  21  * @extends Ext.data.Association
  22  *
  23  * Represents a many to one association with another model. The owner model is expected to have
  24  * a foreign key which references the primary key of the associated model:
  25  *
  26  *     Ext.define('Category', {
  27  *         extend: 'Ext.data.Model',
  28  *         fields: [
  29  *             { name: 'id',   type: 'int' },
  30  *             { name: 'name', type: 'string' }
  31  *         ]
  32  *     });
  33  *
  34  *     Ext.define('Product', {
  35  *         extend: 'Ext.data.Model',
  36  *         fields: [
  37  *             { name: 'id',          type: 'int' },
  38  *             { name: 'category_id', type: 'int' },
  39  *             { name: 'name',        type: 'string' }
  40  *         ],
  41  *         // we can use the belongsTo shortcut on the model to create a belongsTo association
  42  *         associations: [
  43  *             { type: 'belongsTo', model: 'Category' }
  44  *         ]
  45  *     });
  46  *
  47  * In the example above we have created models for Products and Categories, and linked them together
  48  * by saying that each Product belongs to a Category. This automatically links each Product to a Category
  49  * based on the Product's category_id, and provides new functions on the Product model:
  50  *
  51  * ## Generated getter function
  52  *
  53  * The first function that is added to the owner model is a getter function:
  54  *
  55  *     var product = new Product({
  56  *         id: 100,
  57  *         category_id: 20,
  58  *         name: 'Sneakers'
  59  *     });
  60  *
  61  *     product.getCategory(function(category, operation) {
  62  *         // do something with the category object
  63  *         alert(category.get('id')); // alerts 20
  64  *     }, this);
  65  *
  66  * The getCategory function was created on the Product model when we defined the association. This uses the
  67  * Category's configured {@link Ext.data.proxy.Proxy proxy} to load the Category asynchronously, calling the provided
  68  * callback when it has loaded.
  69  *
  70  * The new getCategory function will also accept an object containing success, failure and callback properties
  71  * - callback will always be called, success will only be called if the associated model was loaded successfully
  72  * and failure will only be called if the associatied model could not be loaded:
  73  *
  74  *     product.getCategory({
  75  *         callback: function(category, operation) {}, // a function that will always be called
  76  *         success : function(category, operation) {}, // a function that will only be called if the load succeeded
  77  *         failure : function(category, operation) {}, // a function that will only be called if the load did not succeed
  78  *         scope   : this // optionally pass in a scope object to execute the callbacks in
  79  *     });
  80  *
  81  * In each case above the callbacks are called with two arguments - the associated model instance and the
  82  * {@link Ext.data.Operation operation} object that was executed to load that instance. The Operation object is
  83  * useful when the instance could not be loaded.
  84  *
  85  * ## Generated setter function
  86  *
  87  * The second generated function sets the associated model instance - if only a single argument is passed to
  88  * the setter then the following two calls are identical:
  89  *
  90  *     // this call...
  91  *     product.setCategory(10);
  92  *
  93  *     // is equivalent to this call:
  94  *     product.set('category_id', 10);
  95  *
  96  * If we pass in a second argument, the model will be automatically saved and the second argument passed to
  97  * the owner model's {@link Ext.data.Model#save save} method:
  98  *
  99  *     product.setCategory(10, function(product, operation) {
 100  *         // the product has been saved
 101  *         alert(product.get('category_id')); //now alerts 10
 102  *     });
 103  *
 104  *     //alternative syntax:
 105  *     product.setCategory(10, {
 106  *         callback: function(product, operation), // a function that will always be called
 107  *         success : function(product, operation), // a function that will only be called if the load succeeded
 108  *         failure : function(product, operation), // a function that will only be called if the load did not succeed
 109  *         scope   : this //optionally pass in a scope object to execute the callbacks in
 110  *     })
 111  *
 112  * ## Customisation
 113  *
 114  * Associations reflect on the models they are linking to automatically set up properties such as the
 115  * {@link #primaryKey} and {@link #foreignKey}. These can alternatively be specified:
 116  *
 117  *     Ext.define('Product', {
 118  *         fields: [...],
 119  *
 120  *         associations: [
 121  *             { type: 'belongsTo', model: 'Category', primaryKey: 'unique_id', foreignKey: 'cat_id' }
 122  *         ]
 123  *     });
 124  *
 125  * Here we replaced the default primary key (defaults to 'id') and foreign key (calculated as 'category_id')
 126  * with our own settings. Usually this will not be needed.
 127  */
 128 Ext.define('Ext.data.BelongsToAssociation', {
 129     extend: 'Ext.data.Association',
 130
 131     alias: 'association.belongsto',
 132
 133 <span id='Ext-data-BelongsToAssociation-cfg-foreignKey'>    /**
 134 </span>     * @cfg {String} foreignKey The name of the foreign key on the owner model that links it to the associated
 135      * model. Defaults to the lowercased name of the associated model plus &quot;_id&quot;, e.g. an association with a
 136      * model called Product would set up a product_id foreign key.
 137      *
 138      *     Ext.define('Order', {
 139      *         extend: 'Ext.data.Model',
 140      *         fields: ['id', 'date'],
 141      *         hasMany: 'Product'
 142      *     });
 143      *
 144      *     Ext.define('Product', {
 145      *         extend: 'Ext.data.Model',
 146      *         fields: ['id', 'name', 'order_id'], // refers to the id of the order that this product belongs to
 147      *         belongsTo: 'Group'
 148      *     });
 149      *     var product = new Product({
 150      *         id: 1,
 151      *         name: 'Product 1',
 152      *         order_id: 22
 153      *     }, 1);
 154      *     product.getOrder(); // Will make a call to the server asking for order_id 22
 155      *
 156      */
 157
 158 <span id='Ext-data-BelongsToAssociation-cfg-getterName'>    /**
 159 </span>     * @cfg {String} getterName The name of the getter function that will be added to the local model's prototype.
 160      * Defaults to 'get' + the name of the foreign model, e.g. getCategory
 161      */
 162
 163 <span id='Ext-data-BelongsToAssociation-cfg-setterName'>    /**
 164 </span>     * @cfg {String} setterName The name of the setter function that will be added to the local model's prototype.
 165      * Defaults to 'set' + the name of the foreign model, e.g. setCategory
 166      */
 167
 168 <span id='Ext-data-BelongsToAssociation-cfg-type'>    /**
 169 </span>     * @cfg {String} type The type configuration can be used when creating associations using a configuration object.
 170      * Use 'belongsTo' to create a HasManyAssocation
 171      *
 172      *     associations: [{
 173      *         type: 'belongsTo',
 174      *         model: 'User'
 175      *     }]
 176      */
 177     constructor: function(config) {
 178         this.callParent(arguments);
 179
 180         var me             = this,
 181             ownerProto     = me.ownerModel.prototype,
 182             associatedName = me.associatedName,
 183             getterName     = me.getterName || 'get' + associatedName,
 184             setterName     = me.setterName || 'set' + associatedName;
 185
 186         Ext.applyIf(me, {
 187             name        : associatedName,
 188             foreignKey  : associatedName.toLowerCase() + &quot;_id&quot;,
 189             instanceName: associatedName + 'BelongsToInstance',
 190             associationKey: associatedName.toLowerCase()
 191         });
 192
 193         ownerProto[getterName] = me.createGetter();
 194         ownerProto[setterName] = me.createSetter();
 195     },
 196
 197 <span id='Ext-data-BelongsToAssociation-method-createSetter'>    /**
 198 </span>     * @private
 199      * Returns a setter function to be placed on the owner model's prototype
 200      * @return {Function} The setter function
 201      */
 202     createSetter: function() {
 203         var me              = this,
 204             ownerModel      = me.ownerModel,
 205             associatedModel = me.associatedModel,
 206             foreignKey      = me.foreignKey,
 207             primaryKey      = me.primaryKey;
 208
 209         //'this' refers to the Model instance inside this function
 210         return function(value, options, scope) {
 211             this.set(foreignKey, value);
 212
 213             if (typeof options == 'function') {
 214                 options = {
 215                     callback: options,
 216                     scope: scope || this
 217                 };
 218             }
 219
 220             if (Ext.isObject(options)) {
 221                 return this.save(options);
 222             }
 223         };
 224     },
 225
 226 <span id='Ext-data-BelongsToAssociation-method-createGetter'>    /**
 227 </span>     * @private
 228      * Returns a getter function to be placed on the owner model's prototype. We cache the loaded instance
 229      * the first time it is loaded so that subsequent calls to the getter always receive the same reference.
 230      * @return {Function} The getter function
 231      */
 232     createGetter: function() {
 233         var me              = this,
 234             ownerModel      = me.ownerModel,
 235             associatedName  = me.associatedName,
 236             associatedModel = me.associatedModel,
 237             foreignKey      = me.foreignKey,
 238             primaryKey      = me.primaryKey,
 239             instanceName    = me.instanceName;
 240
 241         //'this' refers to the Model instance inside this function
 242         return function(options, scope) {
 243             options = options || {};
 244
 245             var model = this,
 246                 foreignKeyId = model.get(foreignKey),
 247                 instance,
 248                 args;
 249
 250             if (model[instanceName] === undefined) {
 251                 instance = Ext.ModelManager.create({}, associatedName);
 252                 instance.set(primaryKey, foreignKeyId);
 253
 254                 if (typeof options == 'function') {
 255                     options = {
 256                         callback: options,
 257                         scope: scope || model
 258                     };
 259                 }
 260
 261                 associatedModel.load(foreignKeyId, options);
 262                 model[instanceName] = associatedModel;
 263                 return associatedModel;
 264             } else {
 265                 instance = model[instanceName];
 266                 args = [instance];
 267                 scope = scope || model;
 268
 269                 //TODO: We're duplicating the callback invokation code that the instance.load() call above
 270                 //makes here - ought to be able to normalize this - perhaps by caching at the Model.load layer
 271                 //instead of the association layer.
 272                 Ext.callback(options, scope, args);
 273                 Ext.callback(options.success, scope, args);
 274                 Ext.callback(options.failure, scope, args);
 275                 Ext.callback(options.callback, scope, args);
 276
 277                 return instance;
 278             }
 279         };
 280     },
 281
 282 <span id='Ext-data-BelongsToAssociation-method-read'>    /**
 283 </span>     * Read associated data
 284      * @private
 285      * @param {Ext.data.Model} record The record we're writing to
 286      * @param {Ext.data.reader.Reader} reader The reader for the associated model
 287      * @param {Object} associationData The raw associated data
 288      */
 289     read: function(record, reader, associationData){
 290         record[this.instanceName] = reader.read([associationData]).records[0];
 291     }
 292 });
 293 </pre>
 294 </body>
 295 </html>