extjs-mvc 0.4.0.j → 0.4.0.k

data/lib/extjs-mvc/src/lib/ModelClassManager.js

@@ -0,0 +1,19 @@
+/**
+ * @class ExtMVC.lib.ModelClassManager
+ * @extends ExtMVC.lib.ClassManager
+ * Specialised class manager for managing models
+ */
+ExtMVC.lib.ModelClassManager = Ext.extend(ExtMVC.lib.ClassManager, {
+  //usual model definition stuff to go here
+  define: function(name) {
+    var overrides = this.getRegistered(name);
+    
+    if (overrides == undefined) {
+      throw new Ext.Error(String.format("The {0} model has not been registered yet", name));
+    }
+    
+    return this.constructors[name] = ExtMVC.model.define(name, overrides);
+  }
+});
+
+ExtMVC.registerClassManager('model', new ExtMVC.lib.ModelClassManager());

data/lib/extjs-mvc/src/lib/Route.js

@@ -0,0 +1,139 @@
+/**
+ * @class ExtMVC.router.Route
+ * @extends Object
+ * TODO: [DOCS] Rewrite this horrible nonsense
+ */
+ExtMVC.router.Route = function(mappingString, options) {
+  this.mappingString = mappingString;
+  this.options       = options || {};
+  
+  //The regular expression we use to match a segment of a route mapping
+  //this will recognise segments starting with a colon,
+  //e.g. on 'namespace/:controller/:action', :controller and :action will be recognised
+  this.paramMatchingRegex = new RegExp(/:([0-9A-Za-z\_]*)/g);
+  
+  /**
+   * Converts a route string into an array of symbols starting with a colon. e.g.
+   * ":controller/:action/:id" => [':controller', ':action', ':id']
+   */
+  this.paramsInMatchString = this.mappingString.match(this.paramMatchingRegex) || [];
+  this.paramsInStringWithOptions = [];
+  
+  /**1
+   * Store and remove any route conditions specified
+   */
+  this.conditions = this.options.conditions || {};
+  if (this.options.conditions) { delete this.options.conditions; }
+  
+  for (var i=0; i < this.paramsInMatchString.length; i++) {
+    this.paramsInStringWithOptions.push(this.paramsInMatchString[i]);
+  };
+  
+  for (var o in options) {
+    this.paramsInStringWithOptions.push(":" + o);
+  }
+  
+  this.matcherRegex = this.convertToUsableRegex(mappingString);
+};
+
+ExtMVC.router.Route.prototype = {
+  /**
+   * @param {url} The url we want to match against this route to see if it matches
+   * @return {boolean} Returns true if this route matches the url
+   */
+  recognises: function(url) {
+    return this.matcherRegex.test(url);
+  },
+  
+  /**
+   * @param {url} The url we want to provide matches for
+   * @return {Object} Object of all matches for this url, as well as additional params as defined in the route
+   */
+  matchesFor: function(url) {
+    if (!this.recognises(url)) {return false;};
+    
+    var parameters = {};
+    
+    var keys   = this.paramsInMatchString;
+    var values = url.match(this.matcherRegex);
+    values.shift(); //first value is the entire match so reject
+    
+    for (var i = keys.length - 1; i >= 0; i--){
+      parameters[keys[i].replace(":", "")] = values[i];
+    };
+    
+    //add any additional parameter options specified in the route definition
+    for (option in this.options) {
+      parameters[option] = this.options[option];
+    }
+    
+    return parameters;
+  },
+  
+  urlForNamed: function(options) {
+    var options = options || {};
+    
+    return this.urlFor(Ext.applyIf(options, this.options));
+  },
+  
+  /**
+   * Attempts to build a url with this route, swapping the placeholders with properties of the options hash
+   */
+  urlFor: function(options) {
+    var url = this.mappingString;
+    
+    for (var o in options) {
+      //values in options must match this.options - e.g. this.options.action must be the same as options.action
+      if (options[o] && this.options[o] && options[o] != this.options[o]) { return false; }
+    }
+    
+    
+    //TODO: Tidy this up.  All of it
+
+    var paramsInOptions = [];
+    for (var o in options) {
+      paramsInOptions.push(":" + o);
+    }
+    
+    paramsInOptions = paramsInOptions.sort();
+    var paramsInStringWithOptions = this.paramsInStringWithOptions.sort();
+    
+    //make sure that all match elements in the url string are included.  If not, return false
+    if (paramsInStringWithOptions.length != paramsInOptions.length) { return false; }
+    for (var i=0; i < paramsInOptions.length; i++) {
+      if (paramsInOptions[i] != paramsInStringWithOptions[i]) {
+        return false;
+      }
+    };
+    
+    for (var o in options) {
+      url = url.replace(":" + o, options[o]);
+    }
+    
+    return url;
+  },
+  
+  /**
+   * Private: For a given string, replaces all substrings starting with a colon into
+   * a regex string that can match a url segment. 
+   * e.g. :controller/:action => '^([a-zA-Z0-9\_]+)/([a-zA-Z0-9\_]+)$'
+   * If any conditions have been specified on this route, their regular expressions are used instead:
+   * :controller/:action/:id => '^([a-zA-Z0-9\_]+)/([a-zA-Z0-9\_]+)/([0-9]+)$'
+   * if conditions was set to {":id" =>/[0-9]+]/}
+   * @param {String} regex_string The string we want to turn into a matchable regex
+   * @return {String} The replaced string
+   */
+  convertToUsableRegex: function(regex_string) {
+    var p = this.paramsInMatchString;
+    
+    for (var i = p.length - 1; i >= 0; i--){
+      var cond = this.conditions[p[i]];
+      var matcher = String.format("({0})", cond || "[a-zA-Z0-9\_,]+");
+      
+      regex_string = regex_string.replace(new RegExp(p[i]), matcher);
+    };
+    
+    //we want to match the whole string, so include the anchors
+    return new RegExp("^" + regex_string + "$");
+  }
+};

data/lib/extjs-mvc/src/lib/Router.js

@@ -0,0 +1,282 @@
+/**
+ * @class ExtMVC.router.Router
+ * @extends Object
+ * TODO: [DOCS] Give a good description of the Router
+ */
+ExtMVC.router.Router = function() {};
+
+ExtMVC.router.Router.prototype = {
+  
+  /**
+   * @property mappings
+   * @type Array
+   * Readonly. Maintains the collection of defined routes
+   */
+  mappings: [],
+  
+  /**
+   * @property namedRoutes
+   * @type Object
+   * Readonly. Maintains the collection of named routes
+   */
+  namedRoutes: {},
+  
+  /**
+   * Adds a new route to the collection.  Routes are given priority in the order they are added
+   * @param {String} re The regular expression-style string to match (e.g. ":controller/:action/:id")
+   * @param {Object} additional_params Any additional options which will be returned along with the match elements if the route matches
+   * @return {ExtMVC.router.Route} The newly created route object
+   */
+  connect: function(re, additional_params) {
+    var route = new ExtMVC.router.Route(re, additional_params);
+    this.mappings.push(route);
+    
+    return route;
+  },
+  
+  /**
+   * Defines a named route.  This is the same as using connect, but with the option to specify the route by name.  e.g.:
+   * this.name('myRoute', 'my/custom/route/:id', {controller: 'myController', action: 'myAction'});
+   * this.urlFor('myRoute', {id: 100}); //returns 'my/custom/route/100'
+   * @param {String} routeName The string name to give this route
+   * @param {String} re The regular expression-style string to match (e.g. ":controller/:action/:id")
+   * @param {Object} additional_params Any additional options which will be returned along with the match elements if the route matches
+   */
+  name: function(routeName, re, additional_params) {
+    this.namedRoutes[routeName] = this.connect(re, additional_params);
+  },
+  
+  /**
+   * Same as calling connect("", options) - connects the empty route string to a controller/action pair
+   * @params {Object} options An object containing at least a controller and optionally an action (which is otherwise defaulted to index)
+   */
+  root: function(options) {
+    var options = options || {};
+    this.connect("", Ext.applyIf(options, { action: 'index' }));
+  },
+  
+  /**
+   * Adds specific index, new, show and edit routes for this resource. e.g.:
+   * resources('videos') is equivalent to:
+   * name('videos_path',     'videos',          {controller: 'videos', action: 'index'});
+   * name('new_video_path',  'videos/new',      {controller: 'videos', action: 'new'  });
+   * name('video_path',      'videos/:id',      {controller: 'videos', action: 'show' });
+   * name('edit_video_path', 'videos/:id/edit', {controller: 'videos', action: 'edit' });
+   *
+   * You can pass a second parameter which is an options object, e.g.:
+   * resources('videos', {controller: 'myController', myKey: 'myValue'}) sets up the following:
+   * name('videos_path',     'videos',          {controller: 'myController', myKey: 'myValue', action: 'index'});
+   * name('new_video_path',  'videos/new',      {controller: 'myController', myKey: 'myValue', action: 'new'  });
+   * name('video_path',      'videos/:id',      {controller: 'myController', myKey: 'myValue', action: 'show' });
+   * name('edit_video_path', 'videos/:id/edit', {controller: 'myController', myKey: 'myValue', action: 'edit' });
+   * 
+   * Also accepts a series of arguments - resources('videos', 'bookmarks', 'messages')
+   * is the same as calling resources with each
+   *
+   * Finally, this format is also accepted:
+   * resources('videos', 'bookmarks', 'messages', {controller: 'myController', myKey: 'myValue'})
+   * Which is equivalent to calling resources with each of the three strings in turn, each with the
+   * final argument passed as options
+   */
+  resources: function(resource_name, options) {
+    //if we have been passed a bunch of strings, call resources with each
+    if (arguments[1] && typeof(arguments[1]) == 'string') {
+      var lastArg = arguments[arguments.length - 1];
+      
+      var opts = (typeof(lastArg) == 'object') ? lastArg : {};
+      
+      for (var i=0; i < arguments.length; i++) {
+        //don't call with the last argument if it is an object as this is a generic settings object
+        if (!(lastArg === arguments[i] && typeof(lastArg) == 'object')) {
+          this.resources(arguments[i], opts);
+        };
+      };
+      
+      return;
+    };
+    
+    //work out the named route names for index, show, new and edit actions
+    var indexName = String.format("{0}_path",      resource_name.pluralize()  );
+    var newName   = String.format("new_{0}_path",  resource_name.singularize());
+    var showName  = String.format("{0}_path",      resource_name.singularize());
+    var editName  = String.format("edit_{0}_path", resource_name.singularize());
+    
+    //add named routes for index, new, edit and show
+    this.name(indexName, resource_name,               Ext.apply({}, {controller: resource_name, action: 'index'}));
+    this.name(newName,   resource_name + '/new',      Ext.apply({}, {controller: resource_name, action: 'new'  }));
+    this.name(showName,  resource_name + '/:id',      Ext.apply({}, {controller: resource_name, action: 'show', conditions: {':id': "[0-9]+"}}));
+    this.name(editName,  resource_name + '/:id/edit', Ext.apply({}, {controller: resource_name, action: 'edit', conditions: {':id': "[0-9]+"}}));
+  },
+  
+  /**
+   * Given a hash containing at route segment options (e.g. {controller: 'index', action: 'welcome'}),
+   * attempts to generate a url and redirect to it using Ext.History.add.
+   * All arguments are passed through to this.urlFor()
+   * @param {Object} options An object containing url segment options (such as controller and action)
+   * @return {Boolean} True if a url was generated and redirected to
+   */
+  redirectTo: function() {
+    var url = this.urlFor.apply(this, arguments);
+    if (url) {
+      Ext.History.add(url);
+      return true;
+    } else return false;
+  },
+  
+  /**
+   * Constructs and returns a config object for a Ext.History based link to a given url spec.  This does not create
+   * an Ext.Component, only a shortcut to its config.  This is intended for use in quickly generating menu items
+   * @param {Object} urlOptions A standard url generation object, e.g. {controller: 'index', action: 'welcome'}
+   * @param {Object} linkOptions Options for the link itself, e.g. {text: 'My Link Text'}
+   * @return {Object} a constructed config object for the given parameters
+   */
+  linkTo: function(urlOptions, linkOptions) {
+    var linkOptions = linkOptions || {};
+    
+    var url = this.urlFor(urlOptions);
+    if (url) {
+      return Ext.applyIf(linkOptions, {
+        url:     url,
+        cls:     [urlOptions.controller, urlOptions.action, urlOptions.id].join("-").replace("--", "-").replace(/-$/, ""),
+        text:    this.constructDefaultLinkToName(urlOptions, linkOptions),
+        handler: function() {Ext.History.add(url);}
+      });
+    } else throw new Error("No match for that url specification");
+  },
+  
+  /**
+   * Attempts to create good link name for a given object containing action and controller.  Override with your own 
+   * function to create custom link names for your app
+   * @param {Object} urlOptions An object containing at least controller and action properties
+   * @param {Object} linkOptions An object of arbitrary options for the link, initially passed to linkTo.  Not used
+   * in default implementation but could be useful when overriding this method
+   * @return {String} The best-guess link name for the given params.
+   */
+  constructDefaultLinkToName: function(urlOptions, linkOptions) {
+    if (!urlOptions || !urlOptions.controller || !urlOptions.action) {return "";}
+    var linkOptions = linkOptions || {};
+    
+    Ext.applyIf(linkOptions, {
+      singularName: urlOptions.controller.singularize()
+    });
+    
+    var actionName = urlOptions.action.titleize();
+    if (actionName == 'Index') {
+      return "Show " + urlOptions.controller.titleize();
+    } else {
+      return actionName + " " + linkOptions.singularName.titleize();
+    }
+  },
+  
+  /**
+   * @params {String} url The url to be matched by the Router.  Router will match against
+   * all connected matchers in the order they were connected and return an object created
+   * by parsing the url with the first matching matcher as defined using the connect() method
+   * @returns {Object} Object of all matches to this url
+   */
+  recognise: function(url) {
+    for (var i=0; i < this.mappings.length; i++) {
+      var m = this.mappings[i];
+      var match = m.matchesFor(url);
+      if (match) { return match; }
+    };
+    
+    return false;
+  },
+  
+  /**
+   * Takes an object of url generation options such as controller and action.  Returns a generated url.
+   * For a url to be generated, all of these options must match the requirements of at least one route definition
+   * @param {Object/String} options An object containing url options, or a named route string.
+   * @param {Object} namedRouteOptions If using a named route, this object is passed as additional parameters.  e.g:
+   * this.name('myRoute', 'my/custom/route/:id', {controller: 'myController', action: 'myAction'});
+   * this.urlFor('myRoute', {id: 100}); //returns 'my/custom/route/100'
+   * this.urlFor('myRoute', 100);       //returns 'my/custom/route/100' - number argument assumed to be an ID
+   * this.urlFor('myRoute', modelObj);  //returns 'my/custom/route/100' if modelObj is a model object where modelObj.data.id = 100
+   * @return {String} The generated url, or false if there was no match
+   */
+  urlFor: function(options, namedRouteOptions) {
+    var route;
+    
+    //named route
+    if (typeof(options) == 'string') {
+      if (route = this.namedRoutes[options]) {
+        var namedRouteOptions = namedRouteOptions || {};
+        
+        //normalise named route options in case we're passed an integer
+        if (typeof(namedRouteOptions) == 'number') {
+          namedRouteOptions = {id: namedRouteOptions};
+        };
+        
+        //normalise named route options in case we're passed a model instance
+        if (namedRouteOptions.data && namedRouteOptions.data.id) {
+          namedRouteOptions = {id: namedRouteOptions.data.id};
+        };
+        
+        return route.urlForNamed(namedRouteOptions);
+      };
+    } 
+    //non-named route
+    else {
+      for (var i=0; i < this.mappings.length; i++) {
+        route = this.mappings[i]; var u = route.urlFor(options);
+        if (u) { return u; }
+      };
+    };
+    
+    //there were no matches so return false
+    return false;
+  },
+
+  /**
+   * Immediately redirects to the specified route.
+   * @param {String} route The route 
+   */
+  route: function(route) {
+    document.location.hash = route;
+  },
+
+  /**
+   * Creates a handler for redirecting to the specified route
+   * @param {String} route The route
+   * @return {Function} handler A function that redirects to the route
+   */
+  handleRoute: function(url) {
+    return this.route.createDelegate(this, [url]);
+  },
+  
+  //experimental...
+  withOptions: function(options, routes) {
+    var options = options || {};
+    
+    var defaultScope = this;
+    var optionScope  = {};
+    
+    optionScope.prototype = this;
+    Ext.apply(optionScope, {
+      connect: function(re, additional_params) {
+        var additional_params = additional_params || {};
+        Ext.applyIf(additional_params, options);
+        
+        defaultScope.connect.call(defaultScope, re, additional_params);
+      },
+      
+      name: function(routeName, re, additional_params) {
+        var additional_params = additional_params || {};
+        Ext.applyIf(additional_params, options);
+        
+        defaultScope.name.call(defaultScope, routeName, re, additional_params);
+      }
+    });
+    
+    routes.call(this, optionScope);
+  }
+};
+
+/**
+ * Basic default routes.  Redefine this method inside config/routes.js
+ */
+ExtMVC.router.Router.defineRoutes = function(map) {
+  map.connect(":controller/:action");
+  map.connect(":controller/:action/:id");
+};

data/lib/extjs-mvc/src/lib/String.js

@@ -0,0 +1,94 @@
+/**
+ * @class String
+ * Extensions to the String class
+ **/
+
+/**
+ * Capitalizes a string (e.g. ("some test sentence").capitalize() == "Some test sentence")
+ * @return {String} The capitalized String
+ */
+String.prototype.capitalize = function() {
+  return this.charAt(0).toUpperCase() + this.substr(1).toLowerCase();
+};
+
+/**
+ * Puts the string in Title Case (e.g. ("some test sentence").titleize() == "Some Test Sentence")
+ * @return {String} The titleized String
+ */
+String.prototype.titleize = function() {
+  return this.replace(/\w\S*/g, function(txt){return txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase();});
+};
+
+/**
+ * Takes any string and de-underscores and uppercases it
+ * e.g. long_underscored_string => LongUnderscoredString
+ */
+String.prototype.camelize = function() {
+  return this.replace(/_/g, " ").titleize().replace(/ /g, "");
+};
+
+/**
+ * Underscores a string (e.g. (("SomeCamelizedString").underscore() == 'some_camelized_string', 
+ *                             ("some normal string").underscore()  == 'some_normal_string')
+ * @return {String} The underscored string
+ */
+String.prototype.underscore = function() {
+  return this.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/ /g, "_").replace(/^_/, '');
+};
+
+/**
+ * Uses the Inflector to singularize itself (e.g. ("cats").singularize() == 'cat')
+ * @return {String} The singularized version of this string
+ */
+String.prototype.singularize = function() {
+  return ExtMVC.Inflector.singularize(this);
+};
+
+/**
+ * Uses the Inflector to pluralize itself (e.g. ("cat").pluralize() == 'cats')
+ * @return {String} The pluralized version of this string
+ */
+String.prototype.pluralize = function() {
+  return ExtMVC.Inflector.pluralize(this);
+};
+
+/**
+ * Attempts to humanize a name by replacing underscores with spaces. Mainly useful for Ext.Model.Base
+ * @return {String} The humanized string
+ */
+String.prototype.humanize = function() {
+  return this.underscore().replace(/_/g, " ");
+};
+
+/**
+ * Replaces instances of the strings &, >, < and " with their escaped versions
+ * @return {String} The escaped version of the original text
+ */
+String.prototype.escapeHTML = function () {                                       
+  return this.replace(/&/g,'&amp;').replace(/>/g,'&gt;').replace(/</g,'&lt;').replace(/"/g,'&quot;');
+};
+
+/**
+ * Converts this string into a currency, prepended with the given currency symbol
+ * @param {String} symbol The currency symbol to use (defaults to $)
+ */
+String.prototype.toCurrency = function(symbol) {
+  if (typeof(symbol) == 'undefined') {var symbol = '$';}
+  
+  var beforeDecimal = this.split(".")[0],
+      afterDecimal  = this.split(".")[1];
+  
+  var segmentCount      = Math.floor(beforeDecimal.length / 3);
+  var firstSegmentWidth = beforeDecimal.length % 3,
+      pointerPosition   = firstSegmentWidth;
+  
+  var segments = firstSegmentWidth == 0 ? [] : [beforeDecimal.substr(0, firstSegmentWidth)];
+  
+  for (var i=0; i < segmentCount; i++) {
+    segments.push(beforeDecimal.substr(firstSegmentWidth + (i * 3), 3));
+  };
+  
+  beforeDecimal = symbol + segments.join(",");
+  
+  return afterDecimal ? String.format("{0}.{1}", beforeDecimal, afterDecimal) : beforeDecimal;
+};