/** * @class Ext.data.schema.Association * @extend Ext.Base * * **This class is never created directly. It should be constructed through associations in `Ext.data.Model`.** * * Associations enable you to express relationships between different {@link Ext.data.Model Models}. Consider * an ecommerce system where Users can place Orders - there is a one to many relationship between these Models, * one user can have many orders (including 0 orders). Here is what a sample implementation of this association * could look like. This example will be referred to in the following sections. * * Ext.define('User', { * extend: 'Ext.data.Model', * fields: [{ * name: 'id', * type: 'int' * }, 'name'] * }); * * Ext.define('Order', { * extend: 'Ext.data.Model', * fields: [{ * name: 'id', * type: 'int' * }, { * name: 'userId', * type: 'int', * reference: 'User' * }] * }); * * # Association Types * * Assocations can describe relationships in 3 ways: * * ## Many To One * * A single entity (`A`) has a relationship with many (`B`) entities. An example of this is * an ecommerce system `User` can have many `Order` entities. * * This can be defined using `Ext.data.schema.ManyToOne` for keyed associations, or * `Ext.data.schema.HasMany` for keyless associations. * * ## One To One * * A less common form of Many To One, a single entity (`A`) has a relationship with at most 1 entity (`B`). This is often * used when partitioning data. For example a `User` may have a single `UserInfo` object that stores extra * metadata about the user. * * This can be defined using `Ext.data.schema.OneToOne` for keyed associations, or * `Ext.data.schema.HasOne` for keyless associations. * * ## Many To Many * * An entity (`A`) may have a have a relationship with many (`B`) entities. That (`B`) entity may also * have a relationship with many `A` entities. For example a single `Student` can have many `Subject` entities and * a single `Subject` can have many `Student` entities. * * This can be defined using `Ext.data.schema.ManyToMany`. Many To Many relationships are readonly unless used with * a `Ext.data.Session`. * * * # Keyed vs Keyless Associations * * Associations can be declared in 2 ways, which are outlined below. * * ## Keyed associations * * A keyed association relies on a field in the model matching the id of another model. Membership is driven by the key. * This is the type of relationship that is typically used in a relational database. * This is declared using the ||reference|| configuration on a model field. An example of this can be seen * above for `User/Order`. * * # Keyless associations * * A keyless association relies on data hierarchy to determine membership. Items are members because they are * contained by another entity. This type of relationship is common with NoSQL databases. * formats. A simple example definition using `User/Order`: * * Ext.define('User', { * extend: 'Ext.data.Model', * fields: [{ * name: 'id', * type: 'int' * }, 'name'], * hasMany: 'Order' * }); * * Ext.define('Order', { * extend: 'Ext.data.Model', * fields: [{ * name: 'id', * type: 'int' * }] * }); * * # Advantages of Associations * Assocations make it easier to work with Models that share a connection. Some of the main functionality includes: * * ## Generated Accessors/Setters * * Associated models will automatically generate named methods that allow for accessing the associated data. * The names for these are created using a {@link Ext.data.schema.Schema Schema}, to provide a consistent and * predictable naming structure. * * Using the example code above, there will be 3 generated methods: * + `User` will have an `orders()` function that returns a `Ext.data.Store` of`Orders`. * + `Order` will have a `getUser` method which will return a `User` Model. * + `Order` will have a `setUser` method that will accept a `User` model or a key value. * * ## Nested Loading * * Nested loading is the ability to load hierarchical associated data from a remote source within a single request. * In the following example, each `User` in the `users` store has an `orders` store. Each `orders` store is populated * with `Order` models read from the request. Each `Order` model also has a reference back to the appropriate `User`. * * // Sample JSON data returned by /Users * [{ * "id": 1, * "name": "User Foo", * "orders": [{ * "id": 101, * "userId": 1 * }, { * "id": 102, * "userId": 1 * }, { * "id": 103, * "userId": 1 * }] * }, { * "id": 2, * "name": "User Bar", * "orders": [{ * "id": 201, * "userId": 2 * }, { * "id": 202, * "userId": 2 * }] * }] * * // Application code * var users = new Ext.data.Store({ * model: 'User', * proxy: { * type: 'ajax', * url: '/Users' * } * }); * users.load(function() { * var user1 = users.first(), * user2 = users.last(), * orders1 = user1.orders(), * orders2 = user2.orders(); * * // 3 orders, same reference back to user1 * console.log(orders1.getCount(), orders1.first().getUser() === user1); * // 2 orders, same reference back to user2 * console.log(orders2.getCount(), orders2.first().getUser() === user2); * }); * * ## Binding * * Data binding using {@link Ext.app.ViewModel ViewModels} have functionality to be able to recognize * associated data as part of a bind statement. For example: * + `{user.orders}` binds to the orders store for a user. * + `{order.user.name}` binds to the name of the user taken from the order. * * * # Association Concepts * * ## Roles * * The role is used to determine generated names for an association. By default, the role is generated from * either the field name (in a keyed association) or the model name. This naming follows a pattern defined by * the `Ext.data.schema.Namer`. To change a specific instance, an explicit role can be specified: * * Ext.define('Thread', { * extend: 'Ext.data.Model', * fields: ['id', 'title'] * }); * * Ext.define('Post', { * extend: 'Ext.data.Model', * fields: ['id', 'content', { * name: 'threadId', * reference: { * type: 'Thread', * role: 'discussion', * inverse: 'comments' * * } * }] * }); * * In the above example, the `Thread` will be decorated with a `comments` method that returns the store. * The `Post` will be decorated with `getDiscussion/setDiscussion` methods. * * ## Generated Methods * * Associations generate methods to allow reading and manipulation on associated data. * * On records that have a "to many" relationship, a single methods that returns a `Ext.data.Store` is created. * See {@link #storeGetter}. On records that have a "to one" relationship, 2 methods are generated, a * {@link #recordGetter getter} and a {@link #recordSetter setter}. * * ## Reflexive * * Associations are reflexive. By declaring one "side" of the relationship, the other is automatically setup. In * the example below, there is no code in the `Thread` entity regarding the association, however by virtue of the * declaration in post, `Thread` is decorated with the appropriate infrastructure to participate in the association. * * Ext.define('Thread', { * extend: 'Ext.data.Model', * fields: ['id', 'title'] * }); * * Ext.define('Post', { * extend: 'Ext.data.Model', * fields: ['id', 'content', { * name: 'threadId', * reference: 'Thread' * }] * }); * * ## Naming * * Referring to model names in associations depends on their {@link Ext.data.Model#entityName}. See * the "Relative Naming" section in the `Ext.data.schema.Schema` documentation. */ /** * @cfg {String} associationKey * The name of the property in the data to read the association from. Defaults to the * name of the associated model. */ /** * @method storeGetter * ** This is not a real method, it is placeholder documentation for a generated method on a `Ext.data.Model`. ** * * Gets a store configured with the model of the "many" record. * @param {Object/Function} [options] The options for the getter, or a callback function to execute. If specified as * a function, it will act as the `callback` option. * * @param {Boolean} [options.reload] `true` to force the store to reload from the server. * * @param {Object} [options.scope] The `this` reference for the callback. Defaults to the record. * * @param {Function} [options.success] A function to execute when the store loads successfully. * If the store has already loaded, this will be called immediately and the `Operation` will be `null`. * The success is passed the following parameters: * @param {Ext.data.Store} [options.success.store] The store. * @param {Ext.data.operation.Operation} [options.success.operation] The operation. `null` if no load occurred. * * @param {Function} [options.failure] A function to execute when the store load fails. * If the store has already loaded, this will not be called. * The failure is passed the following parameters: * @param {Ext.data.Store} [options.failure.store] The store. * @param {Ext.data.operation.Operation} [options.failure.operation] The operation * * @param {Function} [options.callback] A function to execute when the store loads, whether it is successful * or failed. If the store has already loaded, this will be called immediately and the `Operation` will be `null`. * The callback is passed the following parameters: * @param {Ext.data.Store} [options.callback.store] The store. * @param {Ext.data.operation.Operation} [options.callback.operation] The operation. `null` if no load occurred. * @param {Boolean} [options.callback.success] `true` if the load was successful. If already loaded this * will always be true. * * @param {Object} [scope] The `this` reference for the callback. Defaults to the record. * * @return {Ext.data.Store} The store. */ /** * @method recordGetter * ** This is not a real method, it is placeholder documentation for a generated method on a `Ext.data.Model`. ** * * Gets a model of the "one" type. * @param {Object/Function} [options] The options for the getter, or a callback function to execute. If specified as * a function, it will act as the `callback` option. * * @param {Boolean} [options.reload] `true` to force the record to reload from the server. * * @param {Object} [options.scope] The `this` reference for the callback. Defaults to the record. * * @param {Function} [options.success] A function to execute when the record loads successfully. * If the record has already loaded, this will be called immediately and the `Operation` will be `null`. * The success is passed the following parameters: * @param {Ext.data.Model} [options.success.record] The record. * @param {Ext.data.operation.Operation} [options.success.operation] The operation. `null` if no load occurred. * * @param {Function} [options.failure] A function to execute when the record load fails. * If the record has already loaded, this will not be called. * The failure is passed the following parameters: * @param {Ext.data.Model} [options.failure.record] The record. * @param {Ext.data.operation.Operation} [options.failure.operation] The operation * * @param {Function} [options.callback] A function to execute when the record loads, whether it is successful * or failed. If the record has already loaded, this will be called immediately and the `Operation` will be `null`. * The callback is passed the following parameters: * @param {Ext.data.Model} [options.callback.record] The record. * @param {Ext.data.operation.Operation} [options.callback.operation] The operation. `null` if no load occurred. * @param {Boolean} [options.callback.success] `true` if the load was successful. If already loaded this * will always be true. * * @param {Object} [scope] The `this` reference for the callback. Defaults to the record. * @return {Ext.data.Model} The record. `null` if the reference has been previously specified as empty. */ /** * @method recordSetter ** This is not a real method, it is placeholder documentation for a generated method on a `Ext.data.Model`. ** * * Sets a model of the "one" type. * @param {Ext.data.Model/Object} value The value to set. This can be a model instance, a key value (if a keyed association) or `null` * to clear the value. * * @param {Object/Function} [options] Options to handle callback. If specified as * a function, it will act as the `callback` option. If specified as an object, the params are the same as * {@link Ext.data.Model#save}. If options is specified, {@link Ext.data.Model#save} will be called on this record. */ /** * @cfg {String} name * The name of this association. */