extjs-mvc 0.4.0.j → 0.4.0.k

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

@@ -0,0 +1,229 @@
+/**
+ * @class ExtMVC.lib.ViewClassManager
+ * @extends ExtMVC.lib.ClassManager
+ * Customised class manager for views. Views differ from most other classes as they are namespaced
+ * by view package, so they take namespace and name when registering.
+ * VCM will attempt to recursively define view classes that extend others, so if a view's xtype hasn't
+ * been registered with Ext.ComponentMgr yet, VCM will attempt to find that xtype by seeing if any of 
+ * the other registered views have declared that xtype via the 'registerXType' property. If one is found,
+ * VCM will either return its constructor if it is already defined, otherwise it will try to define it first,
+ * again recursing up the inheritance stack if necessary. Example:
+<pre>
+  vcm.register('somePackage', 'someView', {
+    xtype: 'anotherview' //this doesn't exist yet
+  });
+  
+  //anotherview extends the 'myxtype' type, which hasn't been defined yet
+  vcm.register('somePackage', 'someOtherView', {
+    xtype: 'myxtype',
+    registerXType: 'anotherview'
+  });
+  
+  //myview extends panel, and is registered with the 'myxtype' xtype
+  vcm.register('somepackage', 'myview', {
+    xtype: 'panel',
+    registerXType: 'myxtype'
+  });
+  
+  When vcm.getConstructor('somepackage', 'someview') is called, it looks to see if 'anotherview' has
+  been registered with Ext.ComponentMgr first. If it has, it just calls Ext.extend with the config included
+  when registering 'someview', extending the constructor of 'anotherview', and returns the result.
+  
+  If 'anotherview' hasn't yet been registered with Ext.ComponentMgr, it is automatically defined first with
+  this.define. In this case, the parent class of 'anotherview' ('myxtype') hasn't been defined yet either,
+  so again the inheritance chain is automatically traversed, 'myview' is defined and registered to 'myxtype',
+  and the resulting extended class constructor returned so that 'anotherview' can in turn be extended.
+</pre>
+ */
+ExtMVC.lib.ViewClassManager = Ext.extend(ExtMVC.lib.ClassManager, {
+  autoDefine: false,
+  
+  /**
+   * Uses Ext.extend to define a previously registered view class config into a full class.
+   * The new class constructor is then cached in this.constructors, keyed by name.
+   * @param {String} name The name of the view to turn from config object to class constructor
+   */
+  define: function define(name) {
+    var overrides = this.getRegistered(name);
+    if (overrides == undefined) this.throwViewNotFoundError(name);
+    
+    var xtype = overrides.xtype || 'panel';
+    
+    delete overrides.xtype;
+    
+    //extend the class, register it if required
+    var constructor = this.getConstructorForXType(xtype);
+    var klass = Ext.extend(constructor, overrides);
+    
+    if (klass == undefined) {
+      throw new Error(
+        String.format("The {0} view could not be created because the xtype you supplied ('{1}') could not be found", name, overrides.xtype)
+      );
+    }
+    
+    var newXType = overrides.registerXType;
+    if (newXType) {
+      Ext.reg(newXType, klass);
+      this.xtypeLookup[newXType] = klass;
+    }
+    
+    this.constructors[name] = klass;
+    this.fireEvent('class-defined', name, klass);
+    
+    return klass;
+  },
+  
+  /**
+   * Register works slightly differently for views because we use a namespace too,
+   * so convert it here first
+   */
+  register: function register(namespace, name, config) {
+    var viewName = this.buildName(namespace, name);
+    
+    ExtMVC.lib.ViewClassManager.superclass.register.call(this, viewName, config);
+  },
+  
+  getConstructor: function getConstructor(namespace, name) {
+    var viewName = this.buildName(namespace, name);
+    
+    return ExtMVC.lib.ViewClassManager.superclass.getConstructor.call(this, viewName);
+  },
+  
+  /**
+   * @private
+   * Finds the constructor for a registered xtype.
+   * FIXME: This uses a horrible hack and really shouldn't be here at all - the reason being that Ext.ComponentMgr
+   * hides its registered types locally, 
+   * @param {String} xtype The xtype to retrieve a constructor for
+   * @return {Function} The constructor for the xtype requested
+   */
+  getConstructorForXType: function getConstructorForXType(xtype) {
+    var constructor = this.xtypeLookup[xtype];
+    
+    if (constructor == undefined) {
+      for (var className in this.registeredClasses) {
+        var value = this.registeredClasses[className];
+        
+        //extend the parent object and register the constructor
+        if (value.registerXType == xtype) {
+          constructor = this.getConstructor(className.split('-')[0], className.split('-')[1]);
+        }
+      }
+    }
+    
+    return constructor;
+  },
+  
+  /**
+   * Because views are named by namespace and name, we need to turn these 2 names into 1
+   * to be able to register them, which is what this function does
+   * @param {String} namespace The view namespace
+   * @param {String} name The view name
+   * @return {String} The composited view name (defaults to "{namespace}-{name}")
+   */
+  buildName: function buildName(namespace, name) {
+    return String.format("{0}-{1}", namespace, name);
+  },
+  
+  xtypeLookup: {
+    box           : Ext.BoxComponent,
+    button        : Ext.Button,
+    buttongroup   : Ext.ButtonGroup,
+    colorpalette  : Ext.ColorPalette,
+    component     : Ext.Component,
+    container     : Ext.Container,
+    cycle         : Ext.CycleButton,
+    dataview      : Ext.DataView,
+    datepicker    : Ext.DatePicker,
+    editor        : Ext.Editor,
+    editorgrid    : Ext.grid.EditorGridPanel,
+    flash         : Ext.FlashComponent,
+    grid          : Ext.grid.GridPanel,
+    listview      : Ext.ListView,
+    panel         : Ext.Panel,
+    progress      : Ext.ProgressBar,
+    propertygrid  : Ext.grid.PropertyGrid,
+    slider        : Ext.Slider,
+    spacer        : Ext.Spacer,
+    splitbutton   : Ext.SplitButton,
+    tabpanel      : Ext.TabPanel,
+    treepanel     : Ext.tree.TreePanel,
+    viewport      : Ext.ViewPort,
+    'window'      : Ext.Window,
+    
+    paging        : Ext.PagingToolbar,
+    toolbar       : Ext.Toolbar,
+    tbbutton      : Ext.Toolbar.Button,
+    tbfill        : Ext.Toolbar.Fill,
+    tbitem        : Ext.Toolbar.Item,
+    tbseparator   : Ext.Toolbar.Separator,
+    tbspacer      : Ext.Toolbar.Spacer,
+    tbsplit       : Ext.Toolbar.SplitButton,
+    tbtext        : Ext.Toolbar.TextItem,
+
+    menu          : Ext.menu.Menu,
+    colormenu     : Ext.menu.ColorMenu,
+    datemenu      : Ext.menu.DateMenu,
+    menubaseitem  : Ext.menu.BaseItem,
+    menucheckitem : Ext.menu.CheckItem,
+    menuitem      : Ext.menu.Item,
+    menuseparator : Ext.menu.Separator,
+    menutextitem  : Ext.menu.TextItem,
+    
+    form          : Ext.FormPanel,
+    checkbox      : Ext.form.Checkbox,
+    checkboxgroup : Ext.form.CheckboxGroup,
+    combo         : Ext.form.ComboBox,
+    datefield     : Ext.form.DateField,
+    displayfield  : Ext.form.DisplayField,
+    field         : Ext.form.Field,
+    fieldset      : Ext.form.FieldSet,
+    hidden        : Ext.form.Hidden,
+    htmleditor    : Ext.form.HtmlEditor,
+    label         : Ext.form.Label,
+    numberfield   : Ext.form.NumberField,
+    radio         : Ext.form.Radio,
+    radiogroup    : Ext.form.RadioGroup,
+    textarea      : Ext.form.TextArea,
+    textfield     : Ext.form.TextField,
+    timefield     : Ext.form.TimeField,
+    trigger       : Ext.form.TriggerField,
+
+    chart         : Ext.chart.Chart,
+    barchart      : Ext.chart.BarChart,
+    cartesianchart: Ext.chart.CartesianChart,
+    columnchart   : Ext.chart.ColumnChart,
+    linechart     : Ext.chart.LineChart,
+    piechart      : Ext.chart.PieChart,
+
+    arraystore    : Ext.data.ArrayStore,
+    directstore   : Ext.data.DirectStore,
+    groupingstore : Ext.data.GroupingStore,
+    jsonstore     : Ext.data.JsonStore,
+    simplestore   : Ext.data.SimpleStore,
+    store         : Ext.data.Store,
+    xmlstore      : Ext.data.XmlStore
+  },
+  
+  /**
+   * @private
+   * Throws a custom Error if the view name has not been registered yet
+   * @param {String} name The name of the view that could not be found
+   */
+  throwViewNotFoundError: function(name) {
+    var dir  = name.split("-")[0],
+        file = name.split("-")[1];
+    
+    var msg = String.format(
+      "The {0} view could not be found, please check that your app/views/{1} directory contains a file called {2}, " +
+      "that the file contains \"{3}\" and that config/environment.json includes this file",
+      name,
+      dir,
+      file,
+      String.format("Ext.registerView('{0}', '{1}')", dir, file)
+    );
+    throw new Error(msg);
+  }
+});
+
+ExtMVC.registerClassManager('view', new ExtMVC.lib.ViewClassManager());

data/lib/extjs-mvc/src/lib/notes.txt

@@ -0,0 +1,32 @@
+/**
+ * Old versions of String extensions.  Not sure if we should be augmenting String like the above so have left this for reference
+ */
+
+// /**
+//  * @param {String} str A string to be capitalized
+//  * @returns A capitalized string (e.g. "some test sentence" becomes "Some test sentence")
+//  * @type String
+//  */
+// String.capitalize = function(str) {
+//   return str.charAt(0).toUpperCase() + str.substr(1).toLowerCase();
+// };
+// 
+// /**
+//  * @param {String} str A string to be turned into title case
+//  * @returns The string in Title Case (e.g. "some test sentence" becomes "Some Test Sentence")
+//  * @type String
+//  */
+// String.titleize = function(str) {
+//   return str.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.camelize = function(class_name_string) {
+//   return String.titleize(class_name_string.replace(/_/g, " ")).replace(/ /g, "");
+// 
+//   // this feels nicer, sadly no collect function (yet) though
+//   // class_name_string.split("_").collect(function(e) {return String.capitalize(e)}).join("");
+// };

data/lib/extjs-mvc/src/model/AdapterManager.js

@@ -0,0 +1,30 @@
+/**
+ * Manages registration and retrieval of MVC Model adapters
+ * @class ExtMVC.model.AdapterManager
+ */
+ExtMVC.model.AdapterManager = {
+  /**
+   * @property adapters
+   * @type Object
+   * Key/Value pairs of registered names and the relevant Adapter objects
+   */
+  adapters: {},
+  
+  /**
+   * Registers an adapter for use with MVC Models.  
+   * @param {String} name String name for this Adapter (e.g. 'REST')
+   * @param {Function} object A reference to the Adapter object itself
+   */
+  register: function(name, constructor) {
+    this.adapters[name] = constructor;
+  },
+  
+  /**
+   * Retrieves the requested adapter by key name
+   * @param {String} name The name of the adapter to fine (e.g. 'REST')
+   * @return {Object/Null} The Adapter object, if found
+   */
+  find: function(name, config) {
+    return this.adapters[name];
+  }
+};

data/lib/extjs-mvc/src/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/extjs-mvc/src/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/extjs-mvc/src/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]);
+      };
+    }
+  };
+};