3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
18 * Associations enable you to express relationships between different {@link Ext.data.Model Models}. Let's say we're
19 * writing an ecommerce system where Users can make Orders - there's a relationship between these Models that we can
22 * Ext.define('User', {
23 * extend: 'Ext.data.Model',
24 * fields: ['id', 'name', 'email'],
26 * hasMany: {model: 'Order', name: 'orders'}
29 * Ext.define('Order', {
30 * extend: 'Ext.data.Model',
31 * fields: ['id', 'user_id', 'status', 'price'],
36 * We've set up two models - User and Order - and told them about each other. You can set up as many associations on
37 * each Model as you need using the two default types - {@link Ext.data.HasManyAssociation hasMany} and {@link
38 * Ext.data.BelongsToAssociation belongsTo}. There's much more detail on the usage of each of those inside their
39 * documentation pages. If you're not familiar with Models already, {@link Ext.data.Model there is plenty on those too}.
43 * - {@link Ext.data.HasManyAssociation hasMany associations}
44 * - {@link Ext.data.BelongsToAssociation belongsTo associations}
45 * - {@link Ext.data.Model using Models}
47 * # Self association models
49 * We can also have models that create parent/child associations between the same type. Below is an example, where
50 * groups can be nested inside other groups:
57 * "name": "Main Group",
61 * "name": "Parent Group"
66 * "name": "Child Group 1"
70 * "name": "Child Group 2"
74 * "name": "Child Group 3"
80 * Ext.define('Group', {
81 * extend: 'Ext.data.Model',
82 * fields: ['id', 'parent_id', 'name'],
95 * foreignKey: 'parent_id',
97 * associationKey: 'child_groups' // read child data from child_groups
102 * foreignKey: 'parent_id',
103 * associationKey: 'parent_group' // read parent data from parent_group
107 * Ext.onReady(function(){
110 * success: function(group){
111 * console.log(group.getGroup().get('name'));
113 * group.groups().each(function(rec){
114 * console.log(rec.get('name'));
122 Ext.define('Ext.data.Association', {
124 * @cfg {String} ownerModel (required)
125 * The string name of the model that owns the association.
129 * @cfg {String} associatedModel (required)
130 * The string name of the model that is being associated with.
134 * @cfg {String} primaryKey
135 * The name of the primary key on the associated model. In general this will be the
136 * {@link Ext.data.Model#idProperty} of the Model.
141 * @cfg {Ext.data.reader.Reader} reader
142 * A special reader to read associated data
146 * @cfg {String} associationKey
147 * The name of the property in the data to read the association from. Defaults to the name of the associated model.
150 defaultReaderType: 'json',
153 create: function(association){
154 if (!association.isAssociation) {
155 if (Ext.isString(association)) {
161 switch (association.type) {
163 return Ext.create('Ext.data.BelongsToAssociation', association);
165 return Ext.create('Ext.data.HasManyAssociation', association);
166 //TODO Add this back when it's fixed
167 // case 'polymorphic':
168 // return Ext.create('Ext.data.PolymorphicAssociation', association);
171 Ext.Error.raise('Unknown Association type: "' + association.type + '"');
180 * Creates the Association object.
181 * @param {Object} [config] Config object.
183 constructor: function(config) {
184 Ext.apply(this, config);
186 var types = Ext.ModelManager.types,
187 ownerName = config.ownerModel,
188 associatedName = config.associatedModel,
189 ownerModel = types[ownerName],
190 associatedModel = types[associatedName],
194 if (ownerModel === undefined) {
195 Ext.Error.raise("The configured ownerModel was not valid (you tried " + ownerName + ")");
197 if (associatedModel === undefined) {
198 Ext.Error.raise("The configured associatedModel was not valid (you tried " + associatedName + ")");
202 this.ownerModel = ownerModel;
203 this.associatedModel = associatedModel;
206 * @property {String} ownerName
207 * The name of the model that 'owns' the association
211 * @property {String} associatedName
212 * The name of the model is on the other end of the association (e.g. if a User model hasMany Orders, this is
217 ownerName : ownerName,
218 associatedName: associatedName
223 * Get a specialized reader for reading associated data
224 * @return {Ext.data.reader.Reader} The reader, null if not supplied
226 getReader: function(){
229 model = me.associatedModel;
232 if (Ext.isString(reader)) {
237 if (reader.isReader) {
238 reader.setModel(model);
240 Ext.applyIf(reader, {
242 type : me.defaultReaderType
245 me.reader = Ext.createByAlias('reader.' + reader.type, reader);
247 return me.reader || null;