For up to date documentation and features, visit http://docs.sencha.com/ext-js/4-0

## Sencha Documentation

# Ext.data.BelongsToAssociation

####

    HierarchyExt.data.AssociationExt.data.BelongsToAssociation

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:

    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'}
    });

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 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 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 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 primaryKey and foreignKey. These can alternatively be specified:

    Ext.define('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.

Defined By

### Config Options

#### Other Configs

Ext.data.Association
view source
associatedModel : String

The string name of the model that is being associated with. Required

The string name of the model that is being associated with. Required

Ext.data.Association
view source
associationKey : String

The name of the property in the data to read the association from. Defaults to the name of the associated model.

The name of the property in the data to read the association from. Defaults to the name of the associated model.

Ext.data.BelongsToAssociation
view source
foreignKey : String
The name of the foreign key on the owner model that links it to the associated model. Defaults to the lowercased name...

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.

    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

Ext.data.BelongsToAssociation
view source
getterName : String
The name of the getter function that will be added to the local model's prototype. Defaults to 'get' + the name of th...

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

Ext.data.Association
view source
ownerModel : String

The string name of the model that owns the association. Required

The string name of the model that owns the association. Required

Ext.data.Association
view source
primaryKey : String
The name of the primary key on the associated model. Defaults to 'id'. In general this will be the Ext.data.Model.idP...

The name of the primary key on the associated model. Defaults to 'id'. In general this will be the Ext.data.Model.idProperty of the Model.

Ext.data.Association
view source
reader : Ext.data.reader.Reader

A special reader to read associated data

A special reader to read associated data

Ext.data.BelongsToAssociation
view source
setterName : String
The name of the setter function that will be added to the local model's prototype. Defaults to 'set' + the name of th...

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

Ext.data.BelongsToAssociation
view source
type : String
The type configuration can be used when creating associations using a configuration object. Use 'belongsTo' to create...

The type configuration can be used when creating associations using a configuration object. Use 'belongsTo' to create a HasManyAssocation

    associations: [{
        type: 'belongsTo',
        model: 'User'
    }]

Defined By

### Properties

Ext.data.Association
view source
associatedName : String

The name of the model is on the other end of the association (e.g. if a User model hasMany Orders, this is 'Order')

The name of the model is on the other end of the association (e.g. if a User model hasMany Orders, this is 'Order')

Ext.data.Association
view source
ownerName : String

The name of the model that 'owns' the association

The name of the model that 'owns' the association

Defined By

### Methods

Ext.data.Association
view source
BelongsToAssociation( Object config) : void

### Parameters

- config : Object

  Optional config object

### Returns

- void

Ext.data.Association
view source
getReader : Ext.data.reader.Reader

Get a specialized reader for reading associated data

Get a specialized reader for reading associated data

### Returns

- Ext.data.reader.Reader

  The reader, null if not supplied