extjs-mvc 0.4.0.j → 0.4.0.k

data/lib/extjs-mvc/src/view/scaffold/New.js

@@ -0,0 +1,20 @@
+/**
+ * @class ExtMVC.view.scaffold.New
+ * @extends ExtMVC.view.scaffold.ScaffoldFormPanel
+ * Shows a generic new form for a given model
+ */
+ExtMVC.registerView('scaffold', 'new', {
+  xtype        : 'scaffold_form',
+  registerXType: 'scaffold_new',
+
+  /**
+   * Sets this panel's title, if not already set.  Also specifies the save handler to use
+   */
+  initComponent: function() {
+    Ext.applyIf(this, {
+      title: 'New ' + this.model.prototype.singularHumanName
+    });
+    
+    ExtMVC.getView('scaffold', 'form').prototype.initComponent.apply(this, arguments);
+  }
+});

data/lib/extjs-mvc/src/view/scaffold/ScaffoldFormPanel.js

@@ -0,0 +1,255 @@
+/**
+ * @class ExtMVC.view.scaffold.ScaffoldFormPanel
+ * @extends Ext.form.FormPanel
+ * Base class for any scaffold form panel (e.g. new and edit forms)
+ */
+ExtMVC.registerView('scaffold', 'form', {
+  xtype        : 'form',
+  registerXType: 'scaffold_form',
+  
+  autoScroll: true,
+  
+  /**
+   * Sets up the FormPanel, adds default configuration and items
+   */
+  constructor: function(config) {
+    var config = config || {};
+    
+    this.model = config.model;
+    
+    if (this.model == undefined) {
+      throw new Ext.Error(String.format("No model supplied to scaffold Form {0}", config.title), config);
+    }
+    
+    Ext.form.FormPanel.prototype.constructor.call(this, config);
+  },
+  
+  /**
+   * Adds default items, keys and buttons to the form
+   */
+  initComponent: function() {
+    Ext.applyIf(this, {
+      items       : this.buildItems(),
+      monitorPoll : 500,
+      keys : [
+        {
+          key:     Ext.EventObject.ESC,
+          scope:   this,
+          handler: this.onCancel
+        },
+        {
+          key:       's',
+          ctrl:      true,
+          scope:     this,
+          stopEvent: true,
+          handler:   this.onSave
+        }
+      ],
+      
+      /**
+       * @property hasSaveButton
+       * @type Boolean
+       * True to include a save button (defaults to true)
+       */
+      hasSaveButton: true,
+
+      /**
+       * @property hasCancelButton
+       * @type Boolean
+       * True to include a cancel button (defaults to true)
+       */
+      hasCancelButton: true
+    });
+    
+    //applyIf applies when buttons: [] is passed, which meant there was no way to
+    //specify any empty set of buttons before
+    if (!Ext.isArray(this.buttons)) {
+      Ext.apply(this, {
+        buttons: this.buildButtons()
+      });
+    }
+    
+    Ext.form.FormPanel.prototype.initComponent.apply(this, arguments);
+    
+    this.initEvents();
+    this.initListeners();
+  },
+  
+  /**
+   * Sets up any listeners on related objects. By default this just listens to update-failed and create-failed
+   * events on the related controller and marks fields as invalid as appropriate
+   */
+  initListeners: function() {
+    if (this.controller) {
+      this.controller.on({
+        scope          : this,
+        'create-failed': this.showErrorsFromInstance,
+        'update-failed': this.showErrorsFromInstance
+      });
+    }
+  },
+  
+  /**
+   * Reads errors from a model instance and marks the relevant fields as invalid
+   * @param {ExtMVC.Model.Base} instance The model instance
+   */
+  showErrorsFromInstance: function(instance) {
+    this.getForm().markInvalid(instance.errors.forForm());
+  },
+  
+  /**
+   * Sets up events emitted by this component
+   */
+  initEvents: function() {
+    this.addEvents(
+      /**
+       * @event save
+       * Fired when the user clicks the save button, or presses ctrl + s
+       * @param {Object} values The values entered into the form
+       * @param {ExtMVC.view.scaffold.ScaffoldFormPanel} this The form panel
+       */
+      'save',
+      
+      /**
+       * @event cancel
+       * Fired when the user clicks the cancel button, or presses the esc key
+       * @param {ExtMVC.Model.Base|Null} instance If editing an existing instance, this is a reference to that instance
+       */
+      'cancel'
+    );
+    
+    //taken from default Ext.FormPanel.initEvents - used to listen to the current validation of the form
+    //and fire off events
+    if (this.monitorValid) this.startMonitoring();
+  },
+  
+  /**
+   * @property formItemConfig
+   * @type Object
+   * Default config which will be passed to all form items
+   */
+  formItemConfig: {
+    anchor: '-40',
+    xtype:  'textfield'
+  },
+  
+  /**
+   * @property ignoreFields
+   * @type Array
+   * An array of fields not to show in the form (defaults to empty)
+   */
+  ignoreFields: ['id', 'created_at', 'updated_at'],
+  
+  /**
+   * Builds the buttons added to this form.  By default this returns an array containing
+   * a Save button and a Cancel button, which fire the 'save' and 'cancel' events respectively
+   * @return {Array} An array of Ext.Button objects or configs
+   */
+  buildButtons: function() {
+    var buttons = [];
+    
+    if (this.hasSaveButton   === true) buttons.push(this.buildSaveButton());
+    if (this.hasCancelButton === true) buttons.push(this.buildCancelButton());
+    
+    return buttons;
+  },
+  
+  /**
+   * Builds the Save button config. Override this to provide your own
+   * @return {Object/Ext.Button} The button config or object
+   */
+  buildSaveButton: function() {
+    return {
+      text:     'Save',
+      scope:    this,
+      iconCls:  'save',
+      handler:  this.onSave,
+      formBind: (this.monitorValid) ? true : false
+    };
+  },
+  
+  /**
+   * Builds the Cancel button config. Override this to provide your own
+   * @return {Object/Ext.Button} The button config or object
+   */
+  buildCancelButton: function() {
+    return {
+      text:     'Cancel',
+      scope:    this,
+      iconCls:  'cancel',
+      handler:  this.onCancel
+    };
+  },
+  
+  /**
+   * Builds an array of form items for the given model
+   * @param {ExtMVC.Model} model The model to build form items for
+   * @return {Array} An array of auto-generated form items
+   */
+  buildItems: function() {
+    items = [];
+    
+    //check to see if FormFields have been created for this model
+    //e.g. for a MyApp.models.User model, checks for existence of MyApp.views.users.FormFields
+    if (this.viewsPackage && this.viewsPackage.FormFields) {
+      items = this.viewsPackage.FormFields;
+    } else {
+      //no user defined form fields, generate them automatically
+      var model  = this.model,
+          proto  = model.prototype,
+          fields = proto.fields;
+      
+      fields.each(function(field) {
+
+        //add if it's not a field to be ignored
+        if (this.ignoreFields.indexOf(field.name) == -1) {
+          items.push(Ext.applyIf({
+            name:        field.name,
+            fieldLabel: (field.name.replace(/_/g, " ")).capitalize()
+          }));
+        }
+      }, this);      
+    }
+    
+    //apply defaults to each item
+    for (var i=0; i < items.length; i++) {
+      if (items[i].layout === undefined) Ext.applyIf(items[i], this.formItemConfig);
+    }
+    
+    return items;
+  },
+  
+  /**
+   * Called when the save button is clicked or CTRL + s pressed.  By default this simply fires
+   * the 'save' event, passing this.getForm().getValues() as the sole argument
+   */
+  onSave: function() {
+    this.fireEvent('save', this.getFormValues(), this);
+  },
+  
+  /**
+   * Gets form values in a nicer way than getForm.getValues() does - calls getValue on each field.
+   * See http://www.diloc.de/blog/2008/03/05/how-to-submit-ext-forms-the-right-way/
+   * @return {Object} key: value pairings of form values
+   */
+  getFormValues: function() {
+    var form   = this.getForm(),
+        values = {};
+    
+    form.items.each(function(item) {
+      var func = (typeof item.getSubmitValue == "function") ? 'getSubmitValue' : 'getValue';
+      
+      values[item.getName()] = item[func]();
+    }, this);
+    
+    return values;
+  },
+  
+  /**
+   * Called when the cancel button is clicked or ESC pressed. Fires the 'cancel' event.  If this is
+   * an edit form the cancel event will be called with a single argument - the current instance
+   */
+  onCancel: function() {
+    this.fireEvent('cancel', this.instance, this);
+  }
+});

data/test/app/vendor/extjs-mvc/App.js

@@ -0,0 +1,219 @@
+/**
+ * @class ExtMVC.App
+ * @extends Ext.util.Observable
+ * @cfg {Boolean} usesHistory True to automatically create required DOM elements for Ext.History,
+ * sets up a listener on Ext.History's change event to fire this.onHistoryChange. False by default
+ */
+ExtMVC.App = Ext.extend(Ext.util.Observable, {
+  /**
+   * @constructor
+   * Sets up the Application - adds events, sets up namespaces, optionally sets up history.
+   * Fires the 'before-launch' event before initializing router, viewport and history.
+   * Calls this.launch() once everything else is set up (override the 'launch' method to provide your own logic).
+   * Fires the 'launched' event after calling this.launch()
+   */
+  constructor: function(config) {
+    ExtMVC.App.superclass.constructor.apply(this, arguments);
+    
+    //apply configuration object and set up namespaces
+    Ext.apply(this, config || {});
+    window[this.name] = this;
+    
+    this.initializeNamespaces();
+    
+    // Ext.onReady(this.onReady, this);
+    
+    this.on('launched', function() {
+      /**
+       * TODO: This used to reside in initializeHistory but this.launch() needs to be
+       * called before this dispatches so it is temporarily here... ugly though
+       */
+      if (this.usesHistory) {
+        if (this.dispatchHistoryOnLoad === true) {
+          Ext.History.init(function(history) {
+            var hash   = document.location.hash.replace("#", "");
+            var params = this.router.recognise(hash);
+            
+            if (params) {this.dispatch(params);}
+          }, this);
+        } else {
+          Ext.History.init();
+        }
+      }      
+    }, this);
+  },
+  
+  /**
+   * @private
+   * Called when Ext.onReady fires
+   */
+  onReady: function() {    
+    if (this.fireEvent('before-launch', this)) {
+      this.initializeRouter();
+      // this.initializeViewport();
+      this.initializeEvents();
+
+      if (this.usesHistory === true) this.initializeHistory();     
+
+      this.launch();
+    }
+  },
+    
+  /**
+   * @property name
+   * @type String
+   * The application's name.  This is used when creating namespaces for models, views and controllers,
+   * and automatically set up as a global variable reference to this application. Read only.
+   */
+  name: 'MyApp',
+    
+  /**
+   * @property usesHistory
+   * @type Boolean
+   * True to automatically create required DOM elements for Ext.History,
+   * sets up a listener on Ext.History's change event to fire this.onHistoryChange. 
+   * False by default
+   */
+  usesHistory: false,
+
+  /**
+   * @prop dispatchHistoryOnLoad
+   * @type Boolean
+   * If usesHistory is true and dispatchHistoryOnLoad is also true, the OS will attempt to match
+   * any string currently after the # in the url and dispatch to it
+   */
+  dispatchHistoryOnLoad: true,
+  
+  /**
+   * Called when the application is booted up. Override this to provide your own startup logic (defaults to Ext.emptyFn)
+   */
+  launch: function() {
+    this.fireEvent('launched', this);
+  },
+  
+  /**
+   * @property params
+   * @type Object
+   * An object containing the most current parameters (usually decoded from a url using this.router)
+   * e.g. {controller: 'index', action: 'welcome', id: 10}
+   */
+  params: {},
+  
+  /**
+   * Dispatches a request to a registered controller. 
+   * @param {Object} dispatchConfig A config object which should look something like this:
+   * {controller: 'MyController', action: 'index'}, where 'MyController' is the key for a controller
+   * which has been registered to the controller.  If action is not specified, it defaults to 'index'
+   * @param {Object} scope The scope in which to fire the event (defaults to the controller)
+   * @param {Array} args An array of arguments which are passed to the controller action.
+   */
+  dispatch: function dispatch(dispatchConfig, scope, args) {
+    var dispatchConfig = dispatchConfig || {};
+    Ext.applyIf(dispatchConfig, {
+      action: 'index'
+    });
+    
+    this.params = dispatchConfig;
+    
+    var c = ExtMVC.getController(dispatchConfig.controller);
+    if (c != undefined) {
+      var action = c[dispatchConfig.action];
+      
+      if (typeof action == "function") action.apply(scope || c, args || []);
+      else throw new Error(String.format("Action '{0}' not found on Controller '{1}'", dispatchConfig.action, dispatchConfig.controller));
+    }
+  },
+  
+  /**
+   * Sets up a Router instance.  This is called automatically before onLaunch()
+   * Add routes using this.router.connect
+   */
+  initializeRouter: function() {
+    if (this.router == undefined) {
+      this.router = new ExtMVC.router.Router();
+      ExtMVC.router.Router.defineRoutes(this.router);
+    }
+  },
+  
+  /**
+   * Uses Ext.namespace to create packages view controllers, models and views
+   * E.g. if name = 'Blog' or this.name = 'Blog', this is the same as:
+   * Ext.ns('Blog', 'Blog.controllers', 'Blog.models', 'Blog.views')
+   */
+  initializeNamespaces: function initializeNamespaces(name) {
+    var name = name || this.name;
+    if (name) {
+      Ext.ns(name, name + '.controllers', name + '.models', name + '.views');
+    };
+  },
+  
+  /**
+   * Creates the necessary DOM elements required for Ext.History to manage state
+   * Sets up listeners on Ext.History's change event to fire the dispatch() action in the normal way.
+   * This is not called automatically as not all applications will need it
+   */
+  initializeHistory: function initializeHistory() {
+    this.historyForm = Ext.getBody().createChild({
+      tag:    'form',
+      action: '#',
+      cls:    'x-hidden',
+      id:     'history-form',
+      children: [
+        {
+          tag: 'div',
+          children: [
+            {
+              tag:  'input',
+              id:   'x-history-field',
+              type: 'hidden'
+            },
+            {
+              tag: 'iframe',
+              id:  'x-history-frame'
+            }
+          ]
+        }
+      ]
+    });
+    
+    Ext.History.on('change', this.onHistoryChange, this);
+  },
+  
+  /**
+   * Takes a history token (anything after the # in the url), consults the router and dispatches
+   * to the appropriate controller and action if a match was found
+   * @param {String} token The url token (e.g. the token would be cont/act/id for a url like mydomain.com/#cont/act/id)
+   */
+  onHistoryChange: function onHistoryChange(token) {
+    var match = this.router.recognise(token);
+    
+    if (match) {
+      this.dispatch(match, null, [{url: token}]);
+    };
+  },
+  
+  /**
+   * Sets up events emitted by the Application
+   */
+  initializeEvents: function initializeEvents() {
+    this.addEvents(
+      /**
+       * @event before-launch
+       * Fires before this application launches
+       * @param {ExtMVC.App} this The application about to be launched
+       */
+      'before-launch',
+
+      /**
+       * @event launched
+       * Fires once the application has been launched
+       * @param {ExtMVC.App} this The application which has been launched
+       */
+      'launched'
+    );
+  }
+});
+
+ExtMVC.App.define = function(config) {
+  ExtMVC.app = new ExtMVC.App(config);
+};