extjs-mvc 0.3.10 → 0.4.0.a

data/lib/js/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/lib/js/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/lib/js/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);

data/lib/js/model/validations/Validations.js

@@ -0,0 +1,276 @@
+Ext.ns('ExtMVC.model.plugin.validation');
+
+/**
+ * @ignore
+ * The Validation classes themselves are defined here.
+ * Subclass ExtMVC.model.plugin.validation.AbstractValidation to create your own validations
+ */
+
+/**
+ * @class ExtMVC.model.plugin.validation.AbstractValidation
+ * Base class for all validations - not used directly, but any of the following may be used:
+<pre><code>
+ExtMVC.model.define("SomeModel", {
+  fields: [
+    {name: 'title',  type: 'string'},
+    {name: 'price',  type: 'int'},
+    {name: 'stock',  type: 'int'},
+    {name: 'gender', type: 'string'},
+    {name: 'colour', type: 'string'}
+  ],
+  
+  validatesPresenceOf : ["title", "price"],
+  validatesLengthOf   : {field: 'title', minimum: 3, maximum: 12},
+  
+  validatesInclusionOf: {field: 'gender', allowed   : ["Male", "Female"]},
+  validatesExclusionOf: {field: 'colour', disallowed: ["Red"]},
+  validatesFormatOf   : {field: 'email',  regex: /someRegex/},
+  
+  validatesNumericalityOf: "stock"
+});
+</code></pre>
+ * 
+ * Most validations will allow an array to be passed to set the validation up on more than one field (e.g.
+ * see the validatesPresenceOf declaration above). If only a string is provided it is assume to be the field name.
+ * The following are all equivalent:
+<pre><code>
+validatesPresenceOf: "title"
+validatesPresenceOf: ["title"]
+validatesPresenceOf: {field: "title"}
+validatesPresenceOf: [{field: "title"}]
+</code></pre>
+ * 
+ * <h2>Running validations</h2>
+ * This plugin overrides ExtMVC.model.Base's usual isValid() function to provide feedback from the validations:
+ * 
+<pre><code>
+var user = new SomeModel({title: "A really long title", colour: "Blue"});
+user.isValid(); //returns false if any of the validations failed
+user.errors; //returns an {@link ExtMVC.model.plugin.validation.Errors Errors} object
+</code></pre>
+ */
+ExtMVC.model.plugin.validation.AbstractValidation = function(ownerClass, field, config) {
+  this.ownerClass = ownerClass;
+  this.field = field;
+  
+  Ext.apply(this, config);
+};
+
+ExtMVC.model.plugin.validation.AbstractValidation.prototype = {
+  /**
+   * Returns the current value of the field to which this validation applies
+   * @param {ExtMVC.model.Base} instance The model instance to get the value from
+   * @return {Mixed} The current value of the field
+   */
+  getValue: function(instance) {
+    return instance.get(this.field);
+  },
+  
+  /**
+   * Empty function which must be overridden by a validation subclass. Make your function return
+   * true if the validation passes, false otherwise
+   * @return {Boolean} True if this validation passes
+   */
+  isValid: function(instance) {
+    return true;
+  }
+};
+
+/**
+ * @class ExtMVC.model.plugin.validation.ValidatesPresenceOf
+ * @extends ExtMVC.model.plugin.validation.AbstractValidation
+ * Ensures that a field is present. See {*link ExtMVC.model.plugin.validation.AbstractValidation AbstractValidation} for example.
+ */
+ExtMVC.model.plugin.validation.ValidatesPresenceOf = Ext.extend(ExtMVC.model.plugin.validation.AbstractValidation, {
+  /**
+   * @property message
+   * @type String
+   * The textual message returned if this validation didn't pass
+   */
+  message: 'must be present',
+  
+  /**
+   * Returns true if the field is an object or a non-empty string
+   * @return {Boolean} True if the field is present
+   */
+  isValid: function(instance) {
+    var value = this.getValue(instance),
+        valid = false;
+    
+    switch(typeof value) {
+      case 'object': if (value != null)     valid = true; break;
+      case 'string': if (value.length != 0) valid = true; break;
+    };
+    
+    return valid;
+  }
+});
+
+/**
+ * @class ExtMVC.model.plugin.validation.ValidatesLengthOf
+ * @extends ExtMVC.model.plugin.validation.AbstractValidation
+ * Returns true if the field is within the length bounds imposed. See {*link ExtMVC.model.plugin.validation.AbstractValidation AbstractValidation} for example.
+ */
+ExtMVC.model.plugin.validation.ValidatesLengthOf = Ext.extend(ExtMVC.model.plugin.validation.AbstractValidation, {
+  
+  /**
+   * @property tooShortMessage
+   * @type String
+   * The message returned if this field was too short
+   */
+  tooShortMessage: 'is too short',
+  
+  /**
+   * @property tooLongMessage
+   * @type String
+   * The message returned if this field was too long
+   */
+  tooLongMessage: 'is too long',
+  
+  message: '',
+
+  /**
+   * Tests that the mimimum and maximum length of this field are met.
+   * Intended to be used on strings and arrays
+   * @return {Boolean} True if the conditions are met
+   */
+  isValid: function(instance) {
+    var value = this.getValue(instance);
+    
+    if (typeof value == 'undefined') return true;
+        
+    if (this.minimum && value.length < this.minimum) {
+      this.message = this.tooShortMessage;
+      return false;
+    }
+    
+    if (this.maximum & value.length > this.maximum) {
+      this.message = this.tooLongMessage;
+      return false;
+    }
+    
+    return true;
+  }
+});
+
+/**
+ * @class ExtMVC.model.plugin.validation.ValidatesNumericalityOf
+ * @extends ExtMVC.model.plugin.validation.AbstractValidation
+ * Ensures that the field is a number. See {*link ExtMVC.model.plugin.validation.AbstractValidation AbstractValidation} for example.
+ */
+ExtMVC.model.plugin.validation.ValidatesNumericalityOf = Ext.extend(ExtMVC.model.plugin.validation.AbstractValidation, {
+  /**
+   * @property message
+   * @type String
+   * The message returned if this field is not a number
+   */
+  message: 'must be a number',
+  
+  /**
+   * Returns true if the typeof this field is a number
+   * @return {Boolean} True if this is a number
+   */
+  isValid: function(instance) {
+    return 'number' == typeof this.getValue(instance);
+  }
+});
+
+/**
+ * @class ExtMVC.model.plugin.validation.ValidatesInclusionOf
+ * @extends ExtMVC.model.plugin.validation.AbstractValidation
+ * Ensures that the field is one of the allowed values. See {*link ExtMVC.model.plugin.validation.AbstractValidation AbstractValidation} for example.
+ */
+ExtMVC.model.plugin.validation.ValidatesInclusionOf = Ext.extend(ExtMVC.model.plugin.validation.AbstractValidation, {
+
+
+  /**
+   * Override Abstract constructor to build the validation message
+   */
+  constructor: function(m, f, config) {
+    //set up defaults
+    config = config || {};
+    Ext.applyIf(config, { allowed: [] });
+    
+    ExtMVC.model.plugin.validation.ValidatesInclusionOf.superclass.constructor.call(this, m, f, config);
+    
+    Ext.applyIf(this, {
+      message: 'must be one of ' + this.allowed.toSentence('or')
+    });
+  },
+  
+  /**
+   * Returns true if the value of this field is one of those specified in this.allowed
+   * @return {Boolean} True if the field's value is allowed
+   */
+  isValid: function(instance) {
+    var value = this.getValue(instance);
+    
+    for (var i=0; i < this.allowed.length; i++) {
+      if (this.allowed[i] == value) return true;
+    };
+    
+    return false;
+  }
+});
+
+/**
+ * @class ExtMVC.model.plugin.validation.ValidatesExclusionOf
+ * @extends ExtMVC.model.plugin.validation.AbstractValidation
+ * Ensures that the field is not one of the allowed values. See {*link ExtMVC.model.plugin.validation.AbstractValidation AbstractValidation} for example.
+ */
+ExtMVC.model.plugin.validation.ValidatesExclusionOf = Ext.extend(ExtMVC.model.plugin.validation.AbstractValidation, {
+
+  /**
+   * Override Abstract constructor to build the validation message
+   * @ignore
+   */
+  constructor: function(m, f, config) {
+    //set up defaults
+    config = config || {};
+    Ext.applyIf(config, { disallowed: [] });
+    
+    ExtMVC.model.plugin.validation.ValidatesExclusionOf.superclass.constructor.call(this, m, f, config);
+    
+    Ext.applyIf(this, {
+      message: 'must not be ' + this.disallowed.toSentence('or')
+    });
+  },
+  
+  /**
+   * Returns true if the value of this field is one of those specified in this.allowed
+   * @return {Boolean} True if the field's value is allowed
+   */
+  isValid: function(instance) {
+    var value = this.getValue(instance),
+        valid = true;
+    
+    for (var i=0; i < this.disallowed.length; i++) {
+      if (this.disallowed[i] == value) valid = false;
+    };
+    
+    return valid;
+  }
+});
+
+/**
+ * @class ExtMVC.model.plugin.validation.ValidatesFormatOf
+ * @extends ExtMVC.model.plugin.validation.AbstractValidation
+ * Ensures that the field matches the given regular expression. See {*link ExtMVC.model.plugin.validation.AbstractValidation AbstractValidation} for example.
+ */
+ExtMVC.model.plugin.validation.ValidatesFormatOf = Ext.extend(ExtMVC.model.plugin.validation.AbstractValidation, {
+  
+  /**
+   * @property message
+   * @type String
+   * The default message to return if this validation does not pass
+   */
+  message: 'is invalid',
+  
+  /**
+   * Returns true if the value of this field matches the suppled regular expression
+   * @return {Boolean} True if the field's value matches
+   */
+  isValid: function(instance) {
+    return this.regex.test(this.getValue(instance));
+  }
+});

data/lib/js/overrides/Ext.Component.js

@@ -0,0 +1,21 @@
+/**
+ * Override how getXTypes works so that it doesn't require that every single class has
+ * an xtype registered for it.
+ */
+Ext.override(Ext.Component, {
+  getXTypes : function(){
+      var tc = this.constructor;
+      if(!tc.xtypes){
+          var c = [], sc = this;
+          while(sc){ //was: while(sc && sc.constructor.xtype) {
+            var xtype = sc.constructor.xtype;
+            if (xtype != undefined) c.unshift(xtype);
+            
+            sc = sc.constructor.superclass;
+          }
+          tc.xtypeChain = c;
+          tc.xtypes = c.join('/');
+      }
+      return tc.xtypes;
+  }
+});