extjs-mvc 0.4.0.j → 0.4.0.k

data/test/app/vendor/extjs-mvc/model/associations/Association.js

@@ -0,0 +1,192 @@
+/**
+ * @class ExtMVC.model.plugin.association
+ * @ignore
+ */
+ExtMVC.model.plugin.association = {
+  /**
+   * This function is called every time a model is created via ExtMVC.model.create
+   * (*NOT* when a model instance is instantiated). Here we initialize associations
+   * on this model.
+   */
+  initialize: function(model) {
+    var proto = model.prototype,
+        assoc = ExtMVC.model.plugin.association;
+    
+    this.resolveDependencies(model);
+    
+    if (proto.hasMany) {
+      Ext.each(this.parseParams(proto.hasMany, 'HasMany'), function(params) {
+        this.define(assoc.HasMany, model, params);
+      }, this);
+    }
+    
+    if (proto.belongsTo) {
+      Ext.each(this.parseParams(proto.belongsTo, 'BelongsTo'), function(params) {
+        this.define(assoc.BelongsTo, model, params);
+      }, this);
+    }
+  },
+  
+  /**
+   * @property dependencies
+   * @type ExtMVC.lib.Dependencies
+   * Dependencies class to manage associations on currently undefined models
+   */
+  dependencies: new ExtMVC.lib.Dependencies(),
+  
+  /**
+   * Defines a new association between two models.  If both models have already been created,
+   * the association is created immediately, otherwise it is deferred until both models have been created
+   * You should never have to call this manually...
+   * @param {Function} constructor The Association constructor to use (one of BelongsTo or HasMany)
+   * @param {ExtMVC.model.Base} model The model which owns the association
+   * @param {Object} params Association params such as associationName and associatedClass
+   */
+  define: function(constructor, model, params) {
+    var modelNS         = ExtMVC.model.modelNamespace,
+        associatedClass = params.associatedClass,
+        modelName       = model.prototype.modelName;
+    
+    if (typeof modelNS[associatedClass] == 'function') {
+      //create the model now
+      this.create.call(this, constructor, modelName, params);
+    } else {
+      //create the model later
+      params.associationConstructor = constructor;
+      this.dependencies.add(associatedClass, modelName, params);
+    }
+  },
+  
+  /**
+   * Creates an association once both models in question have been created
+   * @param {Function} constructor The association constructor (should be HasMany or BelongsTo function)
+   * @param {String} modelName The name of the model on which the association is to be defined
+   * @param {Object} params Parameters for the association, containing at least the following properties:
+   */
+  create: function(constructor, modelName, params) {
+    var modelNS         = ExtMVC.model.modelNamespace,
+        model           = modelNS[modelName],
+        associatedModel = modelNS[params.associatedClass],
+        associationName = params.associationName;
+    
+    model.prototype[associationName] = new constructor(model, associatedModel, params);
+  },
+  
+  /**
+   * This is called immediately by initialize().  Associations are often specified on models that haven't
+   * been created yet, so we keep a list of dependent associations which are to be defined as soon as the
+   * model has been created.  This method is called with the Model constructor function, looks up any associations
+   * that couldn't previously be defined (as this model did not yet exist), and creates them no
+   * @param {ExtMVC.model.Base} model The newly created model
+   */
+  resolveDependencies: function(model) {
+    var dependents = this.dependencies.get(model.prototype.modelName);
+    
+    Ext.each(dependents || [], function(dependent) {
+      var constructor = dependent.config.associationConstructor;
+      delete dependent.config.associationConstructor;
+      
+      this.create(constructor, dependent.name, dependent.config);
+    }, this);
+  },
+  
+  /**
+   * Parses belongsTo and hasMany params into a unified format
+   * @param {Mixed} params String, Object or Array
+   * @param {String} associationType BelongsTo or HasMany - decides how to generate the default association name
+   * @return {Array} An array of normalized params objects
+   */
+  parseParams: function(params, associationType) {
+    var results         = [],
+        associationType = associationType || 'BelongsTo',
+        inflectMethod   = associationType == 'BelongsTo' ? 'singularize' : 'pluralize';
+            
+    /**
+     * We're either passed a string, an object, or an array containing one or more
+     * of each...
+     */
+    if (Ext.isArray(params)) {
+      Ext.each(params, function(association) {
+        results.concat(this.parseParams(association));
+      }, this);
+      return results;
+      
+    } else {
+      if (typeof params == 'string') {
+        params = {associatedClass: params};
+      }
+      
+      var assocClass = params.associatedClass,
+          assocName  = typeof assocClass == 'function'
+                     ? ExtMVC.Inflector[inflectMethod](assocClass.prototype.modelName)
+                     : ExtMVC.Inflector[inflectMethod](assocClass);
+      
+      Ext.applyIf(params, {
+        extend:          {},
+        associationName: assocName
+      });
+      
+      results.push(params);
+    }
+    
+    return results;
+  }
+};
+
+/**
+ * @class ExtMVC.model.plugin.association.Base
+ * Association Base class which provides basic functionality for other Association classes to build upon
+ * Don't use directly - instead use the HasMany or BelongsTo classes.
+ */
+ExtMVC.model.plugin.association.Base = function(ownerClass, associatedClass, config) {
+  config = config || {};
+  
+  this.ownerClass = ownerClass;
+  this.associatedClass = associatedClass;
+  
+  Ext.apply(this, config.extend || {});
+  this.initialConfig = config;
+  
+  this.initialize();
+};
+
+ExtMVC.model.plugin.association.Base.prototype = {
+  /**
+   * Sets up default values for foreignKey
+   */
+  initialize: Ext.emptyFn
+};
+
+/**
+ * @class ExtMVC.model.plugin.association.BelongsTo
+ * @extends ExtMVC.model.plugin.association.Base
+ * A belongsTo association
+ */
+ExtMVC.model.plugin.association.BelongsTo = Ext.extend(ExtMVC.model.plugin.association.Base, {
+  initialize: function() {
+    Ext.apply(this, {
+      name:       ExtMVC.Inflector.singularize(this.associatedClass.prototype.tableName),
+      foreignKey: this.associatedClass.prototype.foreignKeyName
+    });
+  }
+});
+
+/**
+ * @class ExtMVC.model.plugin.association.HasMany
+ * @extends ExtMVC.model.plugin.association.Base
+ * A hasMany association
+ */
+ExtMVC.model.plugin.association.HasMany = Ext.extend(ExtMVC.model.plugin.association.Base, {
+  
+  /**
+   * Set up default values for name etc
+   */
+  initialize: function() {
+    Ext.apply(this, {
+      name:       this.associatedClass.prototype.tableName,
+      foreignKey: this.ownerClass.prototype.foreignKeyName
+    });
+  }
+});
+
+ExtMVC.model.addPlugin(ExtMVC.model.plugin.association);

data/test/app/vendor/extjs-mvc/model/associations/notes.txt

@@ -0,0 +1,87 @@
+/**
+ * Method  Collection Individual
+ * create  yes        yes  (but different)
+ * build   yes        yes
+ * find    yes        no
+ * loaded  yes        yes  (but different)
+ * count   yes        no
+ * destroy yes        yes  (but different)
+ */
+
+/**
+ * Method  HasMany BelongsTo
+ * create  yes     no
+ * build   yes     no
+ * destroy yes     yes
+ * find    yes     yes
+ */
+
+/**
+ * User.find(1, {
+ *   success: function(user) {
+ *     //on belongs to associations
+ *     user.group.destroy();
+ *     user.group.find({success: function(group) {}});
+ *     user.group.set(someGroupInstance); //someGroupInstance must be a saved record (e.g. have an ID)
+ * 
+ *     //on has many associations
+ *     user.posts.destroy(1);
+ *     user.posts.find({id: 1, conditions: [{field: 'title', comparator: '=', value: 'some title'}]}, options);
+ *     user.posts.create(data, options)
+ *     user.posts.build(data)
+ *   }
+ * };
+ */
+
+// ExtMVC.Model.define('User', {
+//   fields:  [],
+//   belongsTo: "Group",
+//   hasMany: [{
+//     name:       'posts',
+//     className:  'Post',
+//     foreignKey: 'user_id',
+//     
+//     extend: {
+//       //some functions
+//     }
+//   }]
+// });
+// 
+// user.posts.find(1, {
+//   success: function() {},
+//   failure: function() {}
+// });
+// 
+// user.posts.create({}, {
+//   success: function() {},
+//   failure: function() {}
+// });
+// 
+// user.posts.build({});
+// 
+// user.posts.loaded();
+// user.posts.count();
+// user.posts.destroy(1);
+// 
+// ExtMVC.Model.define('Post', {
+//   fields:    [],
+//   belongsTo: [{
+//     name:       'user',
+//     className:  'User',
+//     foreignKey: 'user_id',
+//     
+//     extend: {
+//       //some functions
+//     }
+//   }],
+//   hasMany: 'Comment'
+// });
+// 
+// post.user.find();
+// post.user.loaded();
+// post.user.destroy();
+// 
+// ExtMVC.Model.define('Comment', {
+//   fields:    [],
+//   belongsTo: "Post"
+// });

data/test/app/vendor/extjs-mvc/model/validations/Errors.js

@@ -0,0 +1,136 @@
+/**
+ * @class ExtMVC.model.plugin.validation
+ * @ignore
+ */
+
+/**
+ * @class ExtMVC.model.plugin.validation.Errors
+ * Simple class to collect validation errors on a model and return them in various formats. Usage:
+<pre><code>
+ExtMVC.model.define("SomeModel", {
+  fields: [
+    {name: 'title',  type: 'string'},
+    {name: 'price',  type: 'int'},
+    {name: 'stock',  type: 'int'},
+    {name: 'colour', type: 'string'}
+  ],
+  
+  validatesPresenceOf : ["title", "price"],
+  validatesLengthOf   : {field: 'title', minimum: 3, maximum: 12}
+});
+
+var s = new SomeModel({title: 'Some really long title'});
+s.errors; //returns this Errors object
+s.isValid(); //returns false, same as calling s.errors.isValid()
+
+//manually add a validation error on the title field
+s.errors.add('title', 'has an problem of some kind');
+
+this.errors.forField('title'); //returns an array of problems with the title field
+
+this.errors.forForm(); //returns an object suitable for marking fields invalid on a form
+</code></pre>
+ */
+ExtMVC.model.plugin.validation.Errors = function() {
+  /**
+   * @property errors
+   * @type Object
+   * Object containing all errors attached to this model.  This is READ ONLY - do not interact with directly
+   */
+  this.all = {};
+};
+
+ExtMVC.model.plugin.validation.Errors.prototype = {
+  
+  /**
+   * Returns an errors object suitable for applying to a form via BasicForm's markInvalid() method
+   * @return {Object} An object with field IDs as keys and formatted error strings as values
+   */
+  forForm: function() {
+    var formErrors = {};
+    for (key in this.all) {
+      formErrors[key] = this.forField(key, true);
+    }
+    
+    return formErrors;
+  },
+  
+  /**
+   * @property multipleErrorConnector
+   * @type String
+   * The string to use when connecting more than one error (defaults to 'and')
+   */
+  multipleErrorConnector: 'and',
+  
+  /**
+   * Clears out all errors
+   */
+  clear: function() {
+    this.all = {};
+  },
+  
+  /**
+   * Adds an error to a particular field
+   * @param {String} field The field to add an error onto
+   * @param {String} error The error message
+   */
+  add: function(field, error) {
+    this.all[field] = this.all[field] || [];
+    this.all[field].push(error);
+  },
+  
+  /**
+   * Returns an array of all errors for the given field.  Pass true as a second argument to
+   * return a human-readable string, e.g.:
+<pre><code>
+forField('title'); // ['must be present', 'is too short']
+forField('title', true); // 'must be present and is too short'
+</code></pre>
+   * @param {String} field The field to find errors for
+   * @param {Boolean} humanize True to turn the errors array into a human-readable string (defaults to false)
+   * @return {Array|String} An array of errors for this field, or a string 
+   */
+  forField: function(field, humanize) {
+    humanize = humanize || false;
+    var errs = this.all[field] || [];
+        
+    return humanize ? errs.toSentence(this.multipleErrorConnector) : errs;
+  },
+  
+  /**
+   * Returns true if this model currently has no validation errors
+   * @return {Boolean} True if this model is currently valid
+   */
+  isValid: function(paramName) {
+    for (key in this.all) {return false;}
+    
+    return true;
+  },
+  
+  /**
+   * Parses server response to a failed save, adding each error message to the appropriate field.  Override to provide
+   * an implementation for your own server responses.  The default implementation accepts a response like this:
+   * {errors: [['some_field', 'some error regarding some_field'], ['another_field', 'another error']]}
+   * @param {Object/String} serverErrors A errors object returned by server-side validations.  If this is a string it will
+   * @param {Boolean} preserveErrors False to clear all errors before adding errors from server (defaults to false)
+   * automatically be turned into an object via Ext.decode
+   */
+  readServerErrors: function(serverErrors, preserveErrors) {
+    var serverErrors = serverErrors || {};
+    
+    //remove any existing errors unless instructed to preserve them
+    if (preserveErrors !== true) {this.clearErrors();}
+    
+    //make sure we're dealing with an object
+    if (typeof(serverErrors) == 'string') {
+      serverErrors = Ext.decode(serverErrors);
+    };
+    
+    var rawErrors = serverErrors.errors;
+    if (rawErrors) {
+      for (var i=0; i < rawErrors.length; i++) {
+        this.all.push(rawErrors[i]);
+      };
+    };
+  }
+};

data/test/app/vendor/extjs-mvc/model/validations/Plugin.js

@@ -0,0 +1,139 @@
+/**
+ * This is the Validation plugin definition, which mixes in validation.Errors
+ * and some other functions into a model prototype
+ * @ignore
+ */
+
+/**
+ * Overrides Ext.data.Record's isValid() function.
+ * We apply this to Record's prototype as there is no need to define it per model or instance
+ * @ignore
+ */
+Ext.apply(Ext.data.Record.prototype, {
+  isValid: function() {
+    if (this.validations) {
+      if (!this.errors) this.errors = new ExtMVC.model.plugin.validations.Errors();
+      
+      this.errors.clear();
+      
+      //test each validation, add to errors if any fail
+      Ext.each(this.validations, function(validation) {
+        if (!validation.isValid(this)) {
+          this.errors.add(validation.field, validation.message);
+        };
+      }, this);
+    };
+    
+    return this.errors.isValid();
+  }
+});
+
+/**
+ * @ignore
+ * FIXME: This is possibly the most horrendous hack ever. I'm so sorry :(
+ * 
+ * The basic problem is that we need to add an errors object to every Record instance,
+ * which means we need to hook into the constructor somehow.  Sadly everything I tried
+ * to overload the constructor directly failed, so this horrific hack has been done instead
+ */
+(function() {
+  var oldPrototype       = Ext.data.Record.prototype,
+      oldConstructor     = Ext.data.Record,
+      oldFunctionMethods = {};
+
+  for (var method in Ext.data.Record) {
+    oldFunctionMethods[method] = Ext.data.Record[method];
+  }
+
+  Ext.data.Record = function(data, id) {
+    oldConstructor.apply(this, arguments);
+
+    this.errors = new ExtMVC.model.plugin.validation.Errors();
+  };
+
+  for (var method in oldFunctionMethods) {
+    Ext.data.Record[method] = oldFunctionMethods[method];
+  }
+})();
+/**
+ * Again, I'm really sorry :(
+ * @ignore
+ */
+
+/**
+ * @class ExtMVC.model.plugin.validation.Plugin
+ */
+ExtMVC.model.plugin.validation.Plugin = {
+  /**
+   * Initializes this plugin for a given model.  This is called every time a model is *created*
+   * via ExtMVC.model.create, not when a model object is *instantiated*
+   * @param {ExtMVC.model} model The model to initialize the plugin for
+   */
+  initialize: function(model) {
+    this.model = model;
+    
+    Ext.apply(model.prototype, {
+      /**
+       * @property validations
+       * @type Array
+       * An array of all validations performed on this model
+       */
+      validations: this.parseValidations()
+    });
+  },
+  
+  /**
+   * Parses a defined model's prototype for validation declarations and creates validation instances
+   * @return {Array} An Array of validation objects
+   */
+  parseValidations: function() {
+    var validations = [];
+    
+    for (var validation in ExtMVC.model.plugin.validation) {
+      if (/^validate/.test(validation.toLowerCase())) {
+        
+        //for each validation type defined on ExtMVC.model.plugin.validation, check to see if we are using
+        //it in on our model
+        for (var modelKey in this.model.prototype) {
+          if (modelKey.toLowerCase() == validation.toLowerCase()) {
+            //this validation is being used by the model, so add it now
+            var validationConstructor = ExtMVC.model.plugin.validation[validation],
+                validationOptions     = this.model.prototype[modelKey];
+            
+            if (!Ext.isArray(validationOptions)) {
+              validationOptions = [validationOptions];
+            };
+            
+            Ext.each(validationOptions, function(options) {
+              validations.push(this.buildValidation(validationConstructor, options));
+            }, this);
+          };
+        }
+      };
+    }
+    
+    return validations;
+  },
+  
+  /**
+   * Creates a new Validation object based on the passed constructor and options
+   * @param {Function} validation The validation constructor function
+   * @param {Object|String} options A fieldname string, or config object
+   * @return {ExtMVC.model.plugin.validation.AbstractValidation} The validation instance
+   */
+  buildValidation: function(validation, options) {
+    var field, config = {};
+    
+    if (typeof options == 'string') {
+      field = options;
+    } else {
+      field = options.field;
+      delete options.field;
+      config = options;
+    }
+    
+    return new validation(this.model, field, config);
+  }
+};
+
+ExtMVC.model.addPlugin(ExtMVC.model.plugin.validation.Plugin);