extjs-mvc 0.3.10 → 0.4.0.a

data/lib/js/model/Association.js

@@ -0,0 +1,26 @@
+/**
+ * class ExtMVC.model.Association
+ * @ignore
+ */
+ExtMVC.model.Association = {
+  
+  /**
+   * @ignore
+   * Returns the default association name for a given class (e.g. "Post" becomes "posts", "SecretAgent" becomes "secretAgents" etc)
+   * @param {String} className The string name of the class which this belongs to
+   * @return {String} The association name for this class
+   */
+  hasManyAssociationName: function(className) {
+    return className.toLowerCase() + 's';
+  },
+  
+  /**
+   * @ignore
+   * Returns the default association name for a given class (e.g. "Post" becomes "post", "SecretAgent" becomes "secretAgent")
+   * @param {String} className The string name of the class to calculate a belongsTo name for
+   * @return {String} The association name for this class
+   */
+  belongsToAssociationName: function(className) {
+    return className.toLowerCase();
+  }
+};

data/lib/js/model/Base.js

@@ -0,0 +1,63 @@
+/**
+ * @class ExtMVC.model.Base
+ * A set of properties and functions which are applied to all ExtMVC.models when they are defined
+ */
+ExtMVC.model.Base = function() {};
+
+ExtMVC.model.Base.prototype = {
+  
+  /**
+   * @property primaryKey
+   * @type String
+   * The name of the field assumed to be the primary key (defaults to 'id')
+   */
+  primaryKey: 'id',
+  
+  /**
+   * Returns true if this model's primaryKey has not yet been set (i.e. it has not been saved yet)
+   * @return {Boolean} True if this model's primaryKey has not yet been set
+   */
+  newRecord: function() {
+    var id = this.get(this.primaryKey);
+    return typeof id == 'undefined' || id == '';
+  },
+  
+  /**
+   * Returns a unique string for a model instance, suitable for use as a key in a cache (e.g. ExtMVC.model.Cache).
+   * new User({id: 123}).MVCModelId(); //'user-123'
+   * @return {String} The unique key for this model object
+   */
+  MVCModelId: function() {
+    return String.format("{0}-{1}", this.tableName, this.get(this.primaryKey));
+  },
+  
+  /**
+   * Returns a JsonReader suitable for use decoding generic JSON data from a server response
+   * Override this to provide your own Reader
+   */
+  getReader: function() {
+    if (!this.reader) {
+      this.reader = new Ext.data.JsonReader({
+        totalProperty: "results",
+        root:          this.tableName
+      }, this.constructor);
+    }
+    
+    return this.reader;
+  },
+  
+  /**
+   * @property initialize
+   * @type Function
+   * Function which is called whenever a model object is instantiated.  Override this with your own callback if needed
+   */
+  initialize: Ext.emptyFn
+};
+
+
+/**
+ * @ignore
+ * Add the above Base methods and properties to the Ext.data.Record prototype. This means all Record instances
+ * will have MVC models methods, even if not instantiated by an MVC-defined model constructor
+ */
+Ext.apply(Ext.data.Record.prototype, new ExtMVC.model.Base());

data/lib/js/model/BelongsToAssociation.js

@@ -0,0 +1,116 @@
+/**
+ * @class ExtMVC.model.BelongsToAssociation
+ * @extends ExtMVC.model.Association
+ */
+ExtMVC.model.BelongsToAssociation = function(ownerObject, config) {
+  var config = config || {};
+  
+  Ext.applyIf(config, {
+    associationName: ExtMVC.model.Association.belongsToAssociationName(config.name)
+  });
+    
+  //TODO: these should be abstracted to a parent object (as should private vars and funcs below)
+  Ext.applyIf(config, {
+    primaryKey:      'id',
+    foreignKey:      ownerObject.foreignKeyName,
+    extend:          {},
+    
+    className:       (ownerObject.constructor.namespace ? ownerObject.constructor.namespace + '.' + config.name : config.name)
+  });
+  
+  //get a reference to the class definition function of the associated object
+  //(e.g. a hasMany: ['Post'] association will return a reference to Post)
+  var associatedObjectClass = eval(config.className);
+  
+  /**
+   * Private, calls the ownerObject's class method with the supplied args
+   */
+  function callOwnerObjectClassMethod(method, args, scope) {
+    return ownerObject.constructor[method].apply(scope || ownerObject.constructor, args || []);
+  };
+  
+  /**
+   * Private, calls the associated object's class method with the supplied args
+   */
+  function callAssociatedObjectClassMethod (method, args, scope) {
+    return associatedObjectClass[method].apply(scope || associatedObjectClass, args || []);
+  };
+  
+  return {
+    /**
+     * @property associationName
+     * @type String
+     * Returns the name of this association so that the model can add it to its definition
+     */
+    associationName: config.associationName,
+    
+    /**
+     * @property associationClass
+     * @type ExtMVC.model
+     * A reference to the association's class (e.g. belongsTo: "Post" would have associationClass of Post)
+     */
+    associationClass: associatedObjectClass,
+    
+    /**
+     * @property associationType
+     * @type String
+     * The type of association (hasMany or belongsTo)
+     */
+    associationType: 'belongsTo',
+    
+    /**
+     * @property lastFetched
+     * @type Date
+     * Date object representing the last time the associated object was successfully fetched
+     */
+    lastFetched: null,
+    
+    /**
+     * Sets the associated model for this association to the specified model object
+     * @param {ExtMVC.model} modelObject The associated model to set this belongsTo association to
+     */
+    set: function(modelObject) {
+      this.lastFetched = new Date();
+      this.cachedObject = modelObject;
+      
+      //add the foreign key automatically
+      ownerObject.data[modelObject.foreignKeyName] = modelObject.data[config.primaryKey];
+    },
+    
+    /**
+     * Gets the associated model for this association
+     * @param {Object} options Options to pass through to the Ajax load request
+     * @param {Number} cacheFor If the object has been retrieved less than this number of seconds ago, use the cached object
+     */
+    get: function(options, cacheFor) {
+      var options  = options  || {};
+      var cacheFor = cacheFor || 0;
+      
+      Ext.applyIf(options, {
+        loadSuccess: Ext.emptyFn,
+        loadFailure: Ext.emptyFn
+      });
+      
+      var cacheIsCurrent = (((new Date() - this.lastFetched) / 1000) < cacheFor) || (cacheFor == -1);
+      
+      if (this.lastFetched && this.cachedObject && cacheIsCurrent) {
+        //return the cached object via a callback
+        options.loadSuccess.call(options.scope || this, this.cachedObject);
+        
+        //also return via normal return if this is a cached object.  This allows some functions to use the cached object
+        //without the overhead of setting up a callback, so long as they first check that the object has been fetched
+        return this.cachedObject;
+      } else {
+        //inject caching code before loadSuccess - caches the object into this.cachedObject and sets this.lastFetched to now
+        Ext.apply(options, {
+          loadSuccess: options.loadSuccess.createInterceptor(function(obj) {
+            this.cachedObject = obj;
+            this.lastFetched  = new Date();
+          }, this)
+        });
+        
+        return callAssociatedObjectClassMethod('findById', [1, options]);
+      };
+    }
+  };
+};

data/lib/js/model/Cache.js

@@ -0,0 +1,131 @@
+/**
+ * @class ExtMVC.model.Cache
+ * @extends Ext.util.Observable
+ * Provides an interface for caching model objects which have been fetched from some database/backend
+ */
+ExtMVC.model.Cache = function(config) {
+  var config = config || {};
+ 
+  ExtMVC.model.Cache.superclass.constructor.call(this, config);
+  
+  this.addEvents(
+    /**
+     * @event beforeadd
+     * Fires before an item is added to the cache
+     * @param {ExtMVC.model} modelObject The model which is about to be added
+     */
+    'beforeadd',
+    
+    /**
+     * @event add
+     * Fires after an item is added to the cache
+     * @param {ExtMVC.model} modelObject The model which was just added
+     */
+    'add',
+    
+    /**
+     * @event beforeclear
+     * Fires before the cache is cleared
+     * @param {Number} seconds The number of seconds worth of caches which will be saved
+     */
+    'beforeclear',
+    
+    /**
+     * @event clear
+     * Fires after the cache has been cleared
+     * @param {Number} seconds The number of seconds worth of caches which were saved
+     */
+    'clear'
+  );
+};
+
+Ext.extend(ExtMVC.model.Cache, Ext.util.Observable, {
+  
+  /**
+   * @property caches
+   * @type Object
+   * Maintains all cached objects
+   */
+  caches: {},
+  
+  /**
+   * Adds the given model object to the cache.  Automatically stores the datetime of the add
+   * @param {ExtMVC.model} modelObject The model you want to store in the cache
+   */
+  add: function(modelObject) {
+    if (this.fireEvent('beforeadd', modelObject)) {
+      var modelName = modelObject.className;
+      var modelId   = modelObject.data.id;
+
+      if (modelName && modelId) {
+        modelObject.cachedAt = new Date();
+        
+        this.caches[modelName] = this.caches[modelName] || {};        
+        this.caches[modelName][modelId] = modelObject;
+        
+        this.fireEvent('add', modelObject);
+        return true;
+      } else {
+        
+        return false;
+      };
+    }
+  },
+  
+  /**
+   * Fetches an object from the cache
+   * @param {Object} params params object which must contain at least modelName and id.  Optionally 
+   * supply staleTime, which is the number of seconds old the cached object is allowed to be to get a hit,
+   * or a Date which will restrict hits to anything cached after that date
+   * @return {ExtMVC.model/null} The model if found, or null
+   */
+  fetch: function(params) {
+    this.caches[params['modelName']] = this.caches[params['modelName']] || {};
+    
+    var params = params || {};
+    var hit    = this.caches[params['modelName']][params['id']];
+    
+    if (hit) {
+      if (params.staleTime) {
+        if (typeof params.staleTime == 'number') {
+          var date = new Date();
+          date.setTime(date.getTime() - (1000 * params.staleTime));
+          params.staleTime = date;
+        };
+        
+        //make sure we have a date object
+        if (params.staleTime.getTime && hit.cachedAt > params.staleTime) {
+          return hit;
+        }
+      } else {
+        return hit;
+      };
+    };
+  },
+  
+  /**
+   * Clears all objects more than the given number of seconds old (defaults to clearing all objects)
+   * @param {Number} seconds The number of seconds to keep cached objects for (e.g. setting this to 10 would delete anything cached more than 10 seconds ago)
+   */
+  clear: function(seconds) {
+    var seconds = seconds || 0;
+    var date = new Date();
+    date.setTime(date.getTime() - (1000 * seconds));
+    
+    if (this.fireEvent('beforeclear', seconds)) {
+      if (seconds == 0) {
+        this.caches = {};
+      } else {
+        for (var i=0; i < this.caches.length; i++) {
+          for (var j=0; j < this.caches[i].length; j++) {
+            if (this.caches[i][j].cachedAt < date) {
+              delete this.caches[i][j];
+            };
+          };
+        };
+      };
+      
+      this.fireEvent('clear', seconds);
+    }
+  }
+});

data/lib/js/model/HasManyAssociation.js

@@ -0,0 +1,160 @@
+/**
+ * @class ExtMVC.model.HasManyAssociation
+ * @extends ExtMVC.model.Association
+ */
+ExtMVC.model.HasManyAssociation = function(ownerObject, config) {
+  var config = config || {};
+  
+  Ext.applyIf(config, {
+    offset:          0,
+    limit:           25,
+    associationName: ExtMVC.model.Association.hasManyAssociationName(config.name)
+  });
+
+  //TODO: these should be abstracted to a parent object (as should private vars and funcs below)
+  Ext.applyIf(config, {
+    primaryKey:      'id',
+    foreignKey:      ownerObject.foreignKeyName,
+    extend:          {},
+    
+    className:       (ownerObject.constructor.namespace ? ownerObject.constructor.namespace + '.' + config.name : config.name)
+  });
+  
+  //get a reference to the class definition function of the associated object
+  //(e.g. a hasMany: ['Post'] association will return a reference to Post)
+  var associatedObjectClass = eval(config.className);
+  
+  /**
+   * Private, calls the ownerObject's class method with the supplied args
+   */
+  function callOwnerObjectClassMethod(method, args, scope) {
+    return ownerObject.constructor[method].apply(scope || ownerObject.constructor, args || []);
+  };
+  
+  /**
+   * Private, calls the associated object's class method with the supplied args
+   */
+  function callAssociatedObjectClassMethod (method, args, scope) {
+    return associatedObjectClass[method].apply(scope || associatedObjectClass, args || []);
+  }
+  
+  return Ext.applyIf(config.extend, {
+    
+    /**
+     * @property associationName
+     * @type String
+     * Returns the name of this association so that the model can add it to its definition
+     */
+    associationName: config.associationName,
+    
+    /**
+     * @property associationType
+     * @type String
+     * The type of association (hasMany or belongsTo)
+     */
+    associationType: 'hasMany',
+    
+    /**
+     * Returns the URL for this association - e.g. if model User hasMany Posts, user.posts.url() will
+     * return something like /users/1/posts.
+     * Pass additional parameter options as arguments to pass straight through to the URL builder - e.g.:
+     * user.posts.url('published'); // = /users/1/posts/published
+     * @return {String} The URL for the has many resource
+     */
+    url: function() {
+      var args = [ownerObject, associatedObjectClass];
+      for (var i=0; i < arguments.length; i++) {
+        args.push(arguments[i]);
+      };
+      
+      return ExtMVC.UrlBuilder.urlFor.apply(ExtMVC.UrlBuilder, args);
+    },
+    
+    /**
+     * Passes through to the owner class's findById class method, adding a foreign key constraint first
+     * @param {String} id The ID of the associated object to retrieve
+     * @param {Object} options Options passed along to the associated model's Class's findById method.  Pass in loadSuccess, loadFailure, conditions, order etc here
+     */
+    findById: function(id, options) {
+      var options = options || {};
+      
+      //add a condition to constrain to the owner object's id
+      if (!options.conditions) { options.conditions = []; }
+      options.conditions.push({
+        key:   config.foreignKey,
+        value: ownerObject.data[config.primaryKey]
+      });
+      
+      return callAssociatedObjectClassMethod('findById', [id, options]);
+    },
+    
+    findAll: function(storeOptions) {
+      var storeOptions = storeOptions || {};
+      Ext.applyIf(storeOptions, {
+        url: this.url(),
+        
+        listeners: {
+          
+          //Once we have fetched all hasMany records, make sure newRecord is false, and set the parent
+          //relationship to point to this ownerObject (The object which hasMany of these records)
+          'load': {
+            scope: this,
+            fn: function(store, records, options) {
+              Ext.each(records, function(record) {
+                record.newRecord = false;
+                if (record.parent && record.parent.set) {
+                  record.parent.set(ownerObject);
+                }
+              }, this);
+            }
+          }
+        }
+      });
+      
+      return callAssociatedObjectClassMethod('findAll', [storeOptions]);
+    },
+    
+    /**
+     * Creates (builds and attempts to save) this associated model
+     * @param {Object} fields Object with keys and values to initialise this object
+     * @param {Object} saveConfig Passed to the Ext.Ajax request, supply success and failure options here
+     */
+    create: function(fields, saveConfig) {
+      return this.build(fields).save(saveConfig);
+    },
+    
+    /**
+     * Builds an instantiation of the associated model with the supplied data.
+     * Automatically links in the correct foreign key
+     * @param {Object} fields The data to initialize this object with
+     */
+    build: function(fields) {
+      var fields = fields || {};
+      
+      //instantiate the new object with the augmented fields
+      var obj = new associatedObjectClass(fields);
+      
+      //set up the object's belongsTo association.  This also sets up the foreign key
+      var assocName = ExtMVC.model.Association.belongsToAssociationName(ownerObject.className);
+      obj[assocName].set(ownerObject);
+      
+      return obj;
+    },
+
+    /**
+     * Adds an existing (saved) instantiation of the associated model to this model's hasMany collection
+     * @param {ExtMVC.model} modelObject The existing, saved model
+     */
+    add: function(modelObject) {
+      //TODO: implement this
+      
+    },
+
+    destroy: function(id) {
+      //TODO: implement this
+      
+    }
+  });
+};
+
+// Ext.extend(ExtMVC.model.HasManyAssociation, ExtMVC.model.Association);