extjs-rails 4.1.0.alpha1

data/app/assets/javascripts/extjs-rails/src/data/association/HasMany.js

@@ -0,0 +1,289 @@
+/**
+ * @author Ed Spencer
+ * @class Ext.data.association.HasMany
+ * 
+ * <p>Represents a one-to-many relationship between two models. Usually created indirectly via a model definition:</p>
+ * 
+<pre><code>
+Ext.define('Product', {
+    extend: 'Ext.data.Model',
+    fields: [
+        {name: 'id',      type: 'int'},
+        {name: 'user_id', type: 'int'},
+        {name: 'name',    type: 'string'}
+    ]
+});
+
+Ext.define('User', {
+    extend: 'Ext.data.Model',
+    fields: [
+        {name: 'id',   type: 'int'},
+        {name: 'name', type: 'string'}
+    ],
+    // we can use the hasMany shortcut on the model to create a hasMany association
+    hasMany: {model: 'Product', name: 'products'}
+});
+</pre></code>
+* 
+ * <p>Above we created Product and User models, and linked them by saying that a User hasMany Products. This gives
+ * us a new function on every User instance, in this case the function is called 'products' because that is the name
+ * we specified in the association configuration above.</p>
+ * 
+ * <p>This new function returns a specialized {@link Ext.data.Store Store} which is automatically filtered to load
+ * only Products for the given model instance:</p>
+ * 
+<pre><code>
+//first, we load up a User with id of 1
+var user = Ext.create('User', {id: 1, name: 'Ed'});
+
+//the user.products function was created automatically by the association and returns a {@link Ext.data.Store Store}
+//the created store is automatically scoped to the set of Products for the User with id of 1
+var products = user.products();
+
+//we still have all of the usual Store functions, for example it's easy to add a Product for this User
+products.add({
+    name: 'Another Product'
+});
+
+//saves the changes to the store - this automatically sets the new Product's user_id to 1 before saving
+products.sync();
+</code></pre>
+ * 
+ * <p>The new Store is only instantiated the first time you call products() to conserve memory and processing time,
+ * though calling products() a second time returns the same store instance.</p>
+ * 
+ * <p><u>Custom filtering</u></p>
+ * 
+ * <p>The Store is automatically furnished with a filter - by default this filter tells the store to only return
+ * records where the associated model's foreign key matches the owner model's primary key. For example, if a User
+ * with ID = 100 hasMany Products, the filter loads only Products with user_id == 100.</p>
+ * 
+ * <p>Sometimes we want to filter by another field - for example in the case of a Twitter search application we may
+ * have models for Search and Tweet:</p>
+ * 
+<pre><code>
+Ext.define('Search', {
+    extend: 'Ext.data.Model',
+    fields: [
+        'id', 'query'
+    ],
+
+    hasMany: {
+        model: 'Tweet',
+        name : 'tweets',
+        filterProperty: 'query'
+    }
+});
+
+Ext.define('Tweet', {
+    extend: 'Ext.data.Model',
+    fields: [
+        'id', 'text', 'from_user'
+    ]
+});
+
+//returns a Store filtered by the filterProperty
+var store = new Search({query: 'Sencha Touch'}).tweets();
+</code></pre>
+ * 
+ * <p>The tweets association above is filtered by the query property by setting the {@link #filterProperty}, and is
+ * equivalent to this:</p>
+ * 
+<pre><code>
+var store = Ext.create('Ext.data.Store', {
+    model: 'Tweet',
+    filters: [
+        {
+            property: 'query',
+            value   : 'Sencha Touch'
+        }
+    ]
+});
+</code></pre>
+ */
+Ext.define('Ext.data.association.HasMany', {
+    extend: 'Ext.data.association.Association',
+    alternateClassName: 'Ext.data.HasManyAssociation',
+    requires: ['Ext.util.Inflector'],
+
+    alias: 'association.hasmany',
+
+    /**
+     * @cfg {String} foreignKey The name of the foreign key on the associated model that links it to the owner
+     * model. Defaults to the lowercased name of the owner model plus "_id", e.g. an association with a where a
+     * model called Group hasMany Users would create 'group_id' as the foreign key. When the remote store is loaded,
+     * the store is automatically filtered so that only records with a matching foreign key are included in the 
+     * resulting child store. This can be overridden by specifying the {@link #filterProperty}.
+     * <pre><code>
+Ext.define('Group', {
+    extend: 'Ext.data.Model',
+    fields: ['id', 'name'],
+    hasMany: 'User'
+});
+
+Ext.define('User', {
+    extend: 'Ext.data.Model',
+    fields: ['id', 'name', 'group_id'], // refers to the id of the group that this user belongs to
+    belongsTo: 'Group'
+});
+     * </code></pre>
+     */
+    
+    /**
+     * @cfg {String} name The name of the function to create on the owner model to retrieve the child store.
+     * If not specified, the pluralized name of the child model is used.
+     * <pre><code>
+// This will create a users() method on any Group model instance
+Ext.define('Group', {
+    extend: 'Ext.data.Model',
+    fields: ['id', 'name'],
+    hasMany: 'User'
+});
+var group = new Group();
+console.log(group.users());
+
+// The method to retrieve the users will now be getUserList
+Ext.define('Group', {
+    extend: 'Ext.data.Model',
+    fields: ['id', 'name'],
+    hasMany: {model: 'User', name: 'getUserList'}
+});
+var group = new Group();
+console.log(group.getUserList());
+     * </code></pre>
+     */
+    
+    /**
+     * @cfg {Object} storeConfig Optional configuration object that will be passed to the generated Store. Defaults to 
+     * undefined.
+     */
+    
+    /**
+     * @cfg {String} filterProperty Optionally overrides the default filter that is set up on the associated Store. If
+     * this is not set, a filter is automatically created which filters the association based on the configured 
+     * {@link #foreignKey}. See intro docs for more details. Defaults to undefined
+     */
+    
+    /**
+     * @cfg {Boolean} autoLoad True to automatically load the related store from a remote source when instantiated.
+     * Defaults to <tt>false</tt>.
+     */
+    
+    /**
+     * @cfg {String} type The type configuration can be used when creating associations using a configuration object.
+     * Use 'hasMany' to create a HasMany association
+     * <pre><code>
+associations: [{
+    type: 'hasMany',
+    model: 'User'
+}]
+     * </code></pre>
+     */
+    
+    constructor: function(config) {
+        var me = this,
+            ownerProto,
+            name;
+            
+        me.callParent(arguments);
+        
+        me.name = me.name || Ext.util.Inflector.pluralize(me.associatedName.toLowerCase());
+        
+        ownerProto = me.ownerModel.prototype;
+        name = me.name;
+        
+        Ext.applyIf(me, {
+            storeName : name + "Store",
+            foreignKey: me.ownerName.toLowerCase() + "_id"
+        });
+        
+        ownerProto[name] = me.createStore();
+    },
+    
+    /**
+     * @private
+     * Creates a function that returns an Ext.data.Store which is configured to load a set of data filtered
+     * by the owner model's primary key - e.g. in a hasMany association where Group hasMany Users, this function
+     * returns a Store configured to return the filtered set of a single Group's Users.
+     * @return {Function} The store-generating function
+     */
+    createStore: function() {
+        var that            = this,
+            associatedModel = that.associatedModel,
+            storeName       = that.storeName,
+            foreignKey      = that.foreignKey,
+            primaryKey      = that.primaryKey,
+            filterProperty  = that.filterProperty,
+            autoLoad        = that.autoLoad,
+            storeConfig     = that.storeConfig || {};
+        
+        return function() {
+            var me = this,
+                config, filter,
+                modelDefaults = {};
+                
+            if (me[storeName] === undefined) {
+                if (filterProperty) {
+                    filter = {
+                        property  : filterProperty,
+                        value     : me.get(filterProperty),
+                        exactMatch: true
+                    };
+                } else {
+                    filter = {
+                        property  : foreignKey,
+                        value     : me.get(primaryKey),
+                        exactMatch: true
+                    };
+                }
+                
+                modelDefaults[foreignKey] = me.get(primaryKey);
+                
+                config = Ext.apply({}, storeConfig, {
+                    model        : associatedModel,
+                    filters      : [filter],
+                    remoteFilter : false,
+                    modelDefaults: modelDefaults
+                });
+                
+                me[storeName] = new Ext.data.Store(config);
+                if (autoLoad) {
+                    me[storeName].load();
+                }
+            }
+            
+            return me[storeName];
+        };
+    },
+    
+    /**
+     * Read associated data
+     * @private
+     * @param {Ext.data.Model} record The record we're writing to
+     * @param {Ext.data.reader.Reader} reader The reader for the associated model
+     * @param {Object} associationData The raw associated data
+     */
+    read: function(record, reader, associationData){
+        var store = record[this.name](),
+            inverse,
+            items, iLen, i;
+    
+        store.add(reader.read(associationData).records);
+    
+        //now that we've added the related records to the hasMany association, set the inverse belongsTo
+        //association on each of them if it exists
+        inverse = this.associatedModel.prototype.associations.findBy(function(assoc){
+            return assoc.type === 'belongsTo' && assoc.associatedName === record.$className;
+        });
+    
+        //if the inverse association was found, set it now on each record we've just created
+        if (inverse) {
+            items = store.data.items;
+            iLen  = items.length;
+
+            for (i = 0; i < iLen; i++) {
+                items[i][inverse.instanceName] = record;
+            }
+        }
+    }
+});

data/app/assets/javascripts/extjs-rails/src/data/association/HasOne.js

@@ -0,0 +1,304 @@
+/**
+ * @class Ext.data.association.HasOne
+ * 
+ * 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:
+ *
+ *     Ext.define('Address', {
+ *         extend: 'Ext.data.Model',
+ *         fields: [
+ *             { name: 'id',          type: 'int' },
+ *             { name: 'number', type: 'string' },
+ *             { name: 'street', type: 'string' },
+ *             { name: 'city', type: 'string' },
+ *             { name: 'zip', type: 'string' },
+ *         ]
+ *     });
+ *
+ *     Ext.define('Person', {
+ *         extend: 'Ext.data.Model',
+ *         fields: [
+ *             { name: 'id',   type: 'int' },
+ *             { name: 'name', type: 'string' },
+ *             { name: 'address_id', type: 'int'}
+ *         ],
+ *         // we can use the hasOne shortcut on the model to create a hasOne association
+ *         associations: { type: 'hasOne', model: 'Address' }
+ *     });
+ *
+ * In the example above we have created models for People and Addresses, and linked them together
+ * by saying that each Person has a single Address. This automatically links each Person to an Address
+ * based on the Persons address_id, and provides new functions on the Person model:
+ *
+ * ## Generated getter function
+ *
+ * The first function that is added to the owner model is a getter function:
+ *
+ *     var person = new Person({
+ *         id: 100,
+ *         address_id: 20,
+ *         name: 'John Smith'
+ *     });
+ *
+ *     person.getAddress(function(address, operation) {
+ *         // do something with the address object
+ *         alert(address.get('id')); // alerts 20
+ *     }, this);
+ *
+ * The getAddress function was created on the Person model when we defined the association. This uses the
+ * Persons configured {@link Ext.data.proxy.Proxy proxy} to load the Address asynchronously, calling the provided
+ * callback when it has loaded.
+ *
+ * The new getAddress 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:
+ *
+ *     person.getAddress({
+ *         reload: true, // force a reload if the owner model is already cached
+ *         callback: function(address, operation) {}, // a function that will always be called
+ *         success : function(address, operation) {}, // a function that will only be called if the load succeeded
+ *         failure : function(address, 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.
+ * 
+ * Once the getter has been called on the model, it will be cached if the getter is called a second time. To
+ * force the model to reload, specify reload: true in the options object.
+ *
+ * ## 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...
+ *     person.setAddress(10);
+ *
+ *     // is equivalent to this call:
+ *     person.set('address_id', 10);
+ *     
+ * An instance of the owner model can also be passed as a parameter.
+ *
+ * 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:
+ *
+ *     person.setAddress(10, function(address, operation) {
+ *         // the address has been saved
+ *         alert(address.get('address_id')); //now alerts 10
+ *     });
+ *
+ *     //alternative syntax:
+ *     person.setAddress(10, {
+ *         callback: function(address, operation), // a function that will always be called
+ *         success : function(address, operation), // a function that will only be called if the load succeeded
+ *         failure : function(address, 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:
+ *
+ *     Ext.define('Person', {
+ *         fields: [...],
+ *
+ *         associations: [
+ *             { type: 'hasOne', model: 'Address', primaryKey: 'unique_id', foreignKey: 'addr_id' }
+ *         ]
+ *     });
+ *
+ * Here we replaced the default primary key (defaults to 'id') and foreign key (calculated as 'address_id')
+ * with our own settings. Usually this will not be needed.
+ */
+Ext.define('Ext.data.association.HasOne', {
+    extend: 'Ext.data.association.Association',
+    alternateClassName: 'Ext.data.HasOneAssociation',
+
+    alias: 'association.hasone',
+    
+    /**
+     * @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 Person would set up a address_id foreign key.
+     *
+     *     Ext.define('Person', {
+     *         extend: 'Ext.data.Model',
+     *         fields: ['id', 'name', 'address_id'], // refers to the id of the address object
+     *         hasOne: 'Address'
+     *     });
+     *
+     *     Ext.define('Address', {
+     *         extend: 'Ext.data.Model',
+     *         fields: ['id', 'number', 'street', 'city', 'zip'], 
+     *         belongsTo: 'Person'
+     *     });
+     *     var Person = new Person({
+     *         id: 1,
+     *         name: 'John Smith',
+     *         address_id: 13
+     *     }, 1);
+     *     person.getAddress(); // Will make a call to the server asking for address_id 13
+     *
+     */
+
+    /**
+     * @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. getAddress
+     */
+
+    /**
+     * @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. setAddress
+     */
+
+    /**
+     * @cfg {String} type The type configuration can be used when creating associations using a configuration object.
+     * Use 'hasOne' to create a HasOne association.
+     *
+     *     associations: [{
+     *         type: 'hasOne',
+     *         model: 'Address'
+     *     }]
+     */
+    
+    constructor: function(config) {
+        this.callParent(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",
+            instanceName: associatedName + 'HasOneInstance',
+            associationKey: associatedName.toLowerCase()
+        });
+
+        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,
+            foreignKey      = me.foreignKey;
+
+        //'this' refers to the Model instance inside this function
+        return function(value, options, scope) {
+            if (value && value.isModel) {
+                value = value.getId();
+            }
+            
+            this.set(foreignKey, value);
+
+            if (Ext.isFunction(options)) {
+                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.instanceName;
+
+        //'this' refers to the Model instance inside this function
+        return function(options, scope) {
+            options = options || {};
+
+            var model = this,
+                foreignKeyId = model.get(foreignKey),
+                success,
+                instance,
+                args;
+
+            if (options.reload === true || model[instanceName] === undefined) {
+                instance = Ext.ModelManager.create({}, associatedName);
+                instance.set(primaryKey, foreignKeyId);
+
+                if (typeof options == 'function') {
+                    options = {
+                        callback: options,
+                        scope: scope || model
+                    };
+                }
+                
+                // Overwrite the success handler so we can assign the current instance
+                success = options.success;
+                options.success = function(rec){
+                    model[instanceName] = rec;
+                    if (success) {
+                        success.call(this, arguments);
+                    }
+                };
+
+                associatedModel.load(foreignKeyId, options);
+                // assign temporarily while we wait for data to return
+                model[instanceName] = instance;
+                return instance;
+            } else {
+                instance = model[instanceName];
+                args = [instance];
+                scope = scope || model;
+
+                //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.
+                Ext.callback(options, scope, args);
+                Ext.callback(options.success, scope, args);
+                Ext.callback(options.failure, scope, args);
+                Ext.callback(options.callback, scope, args);
+
+                return instance;
+            }
+        };
+    },
+    
+    /**
+     * Read associated data
+     * @private
+     * @param {Ext.data.Model} record The record we're writing to
+     * @param {Ext.data.reader.Reader} reader The reader for the associated model
+     * @param {Object} associationData The raw associated data
+     */
+    read: function(record, reader, associationData){
+        var inverse = this.associatedModel.prototype.associations.findBy(function(assoc){
+            return assoc.type === 'belongsTo' && assoc.associatedName === record.$className;
+        }), newRecord = reader.read([associationData]).records[0];
+        
+        record[this.instanceName] = newRecord;
+    
+        //if the inverse association was found, set it now on each record we've just created
+        if (inverse) {
+            newRecord[inverse.instanceName] = record;
+        }
+    }
+});