/** * @author Ed Spencer * @class Ext.data.BelongsToAssociation * @extends Ext.data.Association * *Represents a one 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:
**var Category = Ext.regModel('Category', { fields: [ {name: 'id', type: 'int'}, {name: 'name', type: 'string'} ] }); var Product = Ext.regModel('Product', { fields: [ {name: 'id', type: 'int'}, {name: 'category_id', type: 'int'}, {name: 'name', type: 'string'} ], 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:
* *Generated getter function
* *The first function that is added to the owner model is a getter function:
** *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} to load the Category asynchronously, calling the provided * callback when it has loaded. 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:
** *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 });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.
* *Generated setter function
* *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:
**//this call product.setCategory(10); //is equivalent to this call: product.set('category_id', 10);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:
** *var Product = Ext.regModel('Product', { fields: [...], associations: [ {type: 'belongsTo', model: 'Category', primaryKey: 'unique_id', foreignKey: 'cat_id'} ] });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.data.BelongsToAssociation = Ext.extend(Ext.data.Association, { /** * @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 "_id", e.g. an association with a * model called Product would set up a product_id foreign key. */ /** * @cfg {String} getterName The name of the getter function that will be added to the local model's prototype. * Defaults to 'get' + the name of the foreign model, e.g. getCategory */ /** * @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 */ constructor: function(config) { Ext.data.BelongsToAssociation.superclass.constructor.apply(this, arguments); var me = this, ownerProto = me.ownerModel.prototype, associatedName = me.associatedName, getterName = me.getterName || 'get' + associatedName, setterName = me.setterName || 'set' + associatedName; Ext.applyIf(me, { name : associatedName, foreignKey: associatedName.toLowerCase() + "_id" }); ownerProto[getterName] = me.createGetter(); ownerProto[setterName] = me.createSetter(); }, /** * @private * Returns a setter function to be placed on the owner model's prototype * @return {Function} The setter function */ createSetter: function() { var me = this, ownerModel = me.ownerModel, associatedModel = me.associatedModel, foreignKey = me.foreignKey, primaryKey = me.primaryKey; //'this' refers to the Model instance inside this function return function(value, options, scope) { this.set(foreignKey, value); if (typeof options == 'function') { options = { callback: options, scope: scope || this }; } if (Ext.isObject(options)) { return this.save(options); } }; }, /** * @private * Returns a getter function to be placed on the owner model's prototype. We cache the loaded instance * the first time it is loaded so that subsequent calls to the getter always receive the same reference. * @return {Function} The getter function */ createGetter: function() { var me = this, ownerModel = me.ownerModel, associatedName = me.associatedName, associatedModel = me.associatedModel, foreignKey = me.foreignKey, primaryKey = me.primaryKey, instanceName = me.name + 'BelongsToInstance'; //'this' refers to the Model instance inside this function return function(options, scope) { options = options || {}; var foreignKeyId = this.get(foreignKey), instance, callbackFn; if (this[instanceName] == undefined) { instance = Ext.ModelMgr.create({}, associatedName); instance.set(primaryKey, foreignKeyId); if (typeof options == 'function') { options = { callback: options, scope: scope || this }; } associatedModel.load(foreignKeyId, options); } else { instance = this[instanceName]; //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. if (typeof options == 'function') { options.call(scope || this, instance); } if (options.success) { options.success.call(scope || this, instance); } if (options.callback) { options.callback.call(scope || this, instance); } return instance; } }; } });