extjs-rails 4.1.0.alpha1

data/app/assets/javascripts/extjs-rails/src/app/Application.js

@@ -0,0 +1,271 @@
+/**
+ * Represents an Ext JS 4 application, which is typically a single page app using a {@link Ext.container.Viewport Viewport}.
+ * A typical Ext.app.Application might look like this:
+ *
+ *     Ext.application({
+ *         name: 'MyApp',
+ *         launch: function() {
+ *             Ext.create('Ext.container.Viewport', {
+ *                 items: {
+ *                     html: 'My App'
+ *                 }
+ *             });
+ *         }
+ *     });
+ *
+ * This does several things. First it creates a global variable called 'MyApp' - all of your Application's classes (such
+ * as its Models, Views and Controllers) will reside under this single namespace, which drastically lowers the chances
+ * of colliding global variables.
+ *
+ * When the page is ready and all of your JavaScript has loaded, your Application's {@link #launch} function is called,
+ * at which time you can run the code that starts your app. Usually this consists of creating a Viewport, as we do in
+ * the example above.
+ *
+ * # Telling Application about the rest of the app
+ *
+ * Because an Ext.app.Application represents an entire app, we should tell it about the other parts of the app - namely
+ * the Models, Views and Controllers that are bundled with the application. Let's say we have a blog management app; we
+ * might have Models and Controllers for Posts and Comments, and Views for listing, adding and editing Posts and Comments.
+ * Here's how we'd tell our Application about all these things:
+ *
+ *     Ext.application({
+ *         name: 'Blog',
+ *         models: ['Post', 'Comment'],
+ *         controllers: ['Posts', 'Comments'],
+ *
+ *         launch: function() {
+ *             ...
+ *         }
+ *     });
+ *
+ * Note that we didn't actually list the Views directly in the Application itself. This is because Views are managed by
+ * Controllers, so it makes sense to keep those dependencies there. The Application will load each of the specified
+ * Controllers using the pathing conventions laid out in the [application architecture guide][mvc] - in this case
+ * expecting the controllers to reside in app/controller/Posts.js and app/controller/Comments.js. In turn, each
+ * Controller simply needs to list the Views it uses and they will be automatically loaded. Here's how our Posts
+ * controller like be defined:
+ *
+ *     Ext.define('MyApp.controller.Posts', {
+ *         extend: 'Ext.app.Controller',
+ *         views: ['posts.List', 'posts.Edit'],
+ *
+ *         //the rest of the Controller here
+ *     });
+ *
+ * Because we told our Application about our Models and Controllers, and our Controllers about their Views, Ext JS will
+ * automatically load all of our app files for us. This means we don't have to manually add script tags into our html
+ * files whenever we add a new class, but more importantly it enables us to create a minimized build of our entire
+ * application using the Ext JS 4 SDK Tools.
+ *
+ * For more information about writing Ext JS 4 applications, please see the [application architecture guide][mvc].
+ *
+ * [mvc]: #/guide/application_architecture
+ *
+ * @docauthor Ed Spencer
+ */
+Ext.define('Ext.app.Application', {
+    extend: 'Ext.app.Controller',
+
+    requires: [
+        'Ext.ModelManager',
+        'Ext.data.Model',
+        'Ext.data.StoreManager',
+        'Ext.tip.QuickTipManager',
+        'Ext.ComponentManager',
+        'Ext.app.EventBus'
+    ],
+
+    /**
+     * @cfg {String} name
+     * The name of your application. This will also be the namespace for your views, controllers
+     * models and stores. Don't use spaces or special characters in the name.
+     */
+
+    /**
+     * @cfg {String[]} controllers
+     * Names of controllers that the app uses.
+     */
+
+    /**
+     * @cfg {Object} scope
+     * The scope to execute the {@link #launch} function in. Defaults to the Application instance.
+     */
+    scope: undefined,
+
+    /**
+     * @cfg {Boolean} enableQuickTips
+     * True to automatically set up Ext.tip.QuickTip support.
+     */
+    enableQuickTips: true,
+
+    /**
+     * @cfg {String} defaultUrl
+     * When the app is first loaded, this url will be redirected to.
+     */
+
+    /**
+     * @cfg {String} appFolder
+     * The path to the directory which contains all application's classes.
+     * This path will be registered via {@link Ext.Loader#setPath} for the namespace specified
+     * in the {@link #name name} config.
+     */
+    appFolder: 'app',
+
+    /**
+     * @cfg {Boolean} autoCreateViewport
+     * True to automatically load and instantiate AppName.view.Viewport before firing the launch function.
+     */
+    autoCreateViewport: false,
+
+    /**
+     * Creates new Application.
+     * @param {Object} [config] Config object.
+     */
+    constructor: function(config) {
+        config = config || {};
+        Ext.apply(this, config);
+
+        var requires = config.requires || [],
+            controllers, ln, i, controller,
+            paths, path, ns;
+
+        Ext.Loader.setPath(this.name, this.appFolder);
+
+        if (this.paths) {
+            paths = this.paths;
+
+            for (ns in paths) {
+                if (paths.hasOwnProperty(ns)) {
+                    path = paths[ns];
+
+                    Ext.Loader.setPath(ns, path);
+                }
+            }
+        }
+
+        this.callParent(arguments);
+
+        this.eventbus = new Ext.app.EventBus;
+
+        controllers = Ext.Array.from(this.controllers);
+        ln = controllers && controllers.length;
+
+        this.controllers = new Ext.util.MixedCollection();
+
+        if (this.autoCreateViewport) {
+            requires.push(this.getModuleClassName('Viewport', 'view'));
+        }
+
+        for (i = 0; i < ln; i++) {
+            requires.push(this.getModuleClassName(controllers[i], 'controller'));
+        }
+
+        Ext.require(requires);
+
+        Ext.onReady(function() {
+            for (i = 0; i < ln; i++) {
+                controller = this.getController(controllers[i]);
+                controller.init(this);
+            }
+
+            this.onBeforeLaunch.call(this);
+        }, this);
+    },
+
+    control: function(selectors, listeners, controller) {
+        this.eventbus.control(selectors, listeners, controller);
+    },
+
+    /**
+     * @method
+     * @template
+     * Called automatically when the page has completely loaded. This is an empty function that should be
+     * overridden by each application that needs to take action on page load.
+     * @param {String} profile The detected {@link #profiles application profile}
+     * @return {Boolean} By default, the Application will dispatch to the configured startup controller and
+     * action immediately after running the launch function. Return false to prevent this behavior.
+     */
+    launch: Ext.emptyFn,
+
+    /**
+     * @private
+     */
+    onBeforeLaunch: function() {
+        var me = this,
+            controllers, c, cLen, controller;
+
+        if (me.enableQuickTips) {
+            Ext.tip.QuickTipManager.init();
+        }
+
+        if (me.autoCreateViewport) {
+            me.getView('Viewport').create();
+        }
+
+        me.launch.call(this.scope || this);
+        me.launched = true;
+        me.fireEvent('launch', this);
+
+        controllers = me.controllers.items;
+        cLen        = controllers.length;
+
+        for (c = 0; c < cLen; c++) {
+            controller = controllers[c];
+            controller.onLaunch(this);
+        }
+    },
+
+    getModuleClassName: function(name, module) {
+        // Deciding if a class name must be qualified:
+        // 1 - if the name doesn't contains at least one dot, we must definitely qualify it
+        // 2 - the name may be a qualified name of a known class, but:
+        // 2.1 - in runtime, the loader may not know the class - specially in production - so we must check the class manager
+        // 2.2 - in build time, the class manager may not know the class, but the loader does, so we check the second one
+        //       (the loader check assures it's really a class, and not a namespace, so we can have 'Books.controller.Books',
+        //       and request for a controller called Books will not be underqualified)
+        if (name.indexOf('.') !== -1 && (Ext.ClassManager.isCreated(name) || Ext.Loader.isAClassNameWithAKnownPrefix(name))) {
+            return name;
+        } else {
+            return this.name + '.' + module + '.' + name;
+        }
+    },
+
+    getController: function(name) {
+        var controller = this.controllers.get(name);
+
+        if (!controller) {
+            controller = Ext.create(this.getModuleClassName(name, 'controller'), {
+                application: this,
+                id: name
+            });
+
+            this.controllers.add(controller);
+        }
+
+        return controller;
+    },
+
+    getStore: function(name) {
+        var store = Ext.StoreManager.get(name);
+
+        if (!store) {
+            store = Ext.create(this.getModuleClassName(name, 'store'), {
+                storeId: name
+            });
+        }
+
+        return store;
+    },
+
+    getModel: function(model) {
+        model = this.getModuleClassName(model, 'model');
+
+        return Ext.ModelManager.getModel(model);
+    },
+
+    getView: function(view) {
+        view = this.getModuleClassName(view, 'view');
+
+        return Ext.ClassManager.get(view);
+    }
+});

data/app/assets/javascripts/extjs-rails/src/app/Controller.js

@@ -0,0 +1,458 @@
+/**
+ * @class Ext.app.Controller
+ *
+ * Controllers are the glue that binds an application together. All they really do is listen for events (usually from
+ * views) and take some action. Here's how we might create a Controller to manage Users:
+ *
+ *     Ext.define('MyApp.controller.Users', {
+ *         extend: 'Ext.app.Controller',
+ *
+ *         init: function() {
+ *             console.log('Initialized Users! This happens before the Application launch function is called');
+ *         }
+ *     });
+ *
+ * The init function is a special method that is called when your application boots. It is called before the
+ * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
+ * your Viewport is created.
+ *
+ * The init function is a great place to set up how your controller interacts with the view, and is usually used in
+ * conjunction with another Controller function - {@link Ext.app.Controller#control control}. The control function
+ * makes it easy to listen to events on your view classes and take some action with a handler function. Let's update
+ * our Users controller to tell us when the panel is rendered:
+ *
+ *     Ext.define('MyApp.controller.Users', {
+ *         extend: 'Ext.app.Controller',
+ *
+ *         init: function() {
+ *             this.control({
+ *                 'viewport > panel': {
+ *                     render: this.onPanelRendered
+ *                 }
+ *             });
+ *         },
+ *
+ *         onPanelRendered: function() {
+ *             console.log('The panel was rendered');
+ *         }
+ *     });
+ *
+ * We've updated the init function to use this.control to set up listeners on views in our application. The control
+ * function uses the new ComponentQuery engine to quickly and easily get references to components on the page. If you
+ * are not familiar with ComponentQuery yet, be sure to check out the {@link Ext.ComponentQuery documentation}. In brief though,
+ * it allows us to pass a CSS-like selector that will find every matching component on the page.
+ *
+ * In our init function above we supplied 'viewport > panel', which translates to "find me every Panel that is a direct
+ * child of a Viewport". We then supplied an object that maps event names (just 'render' in this case) to handler
+ * functions. The overall effect is that whenever any component that matches our selector fires a 'render' event, our
+ * onPanelRendered function is called.
+ *
+ * <u>Using refs</u>
+ *
+ * One of the most useful parts of Controllers is the new ref system. These use the new {@link Ext.ComponentQuery} to
+ * make it really easy to get references to Views on your page. Let's look at an example of this now:
+ *
+ *     Ext.define('MyApp.controller.Users', {
+ *         extend: 'Ext.app.Controller',
+ *
+ *         refs: [
+ *             {
+ *                 ref: 'list',
+ *                 selector: 'grid'
+ *             }
+ *         ],
+ *
+ *         init: function() {
+ *             this.control({
+ *                 'button': {
+ *                     click: this.refreshGrid
+ *                 }
+ *             });
+ *         },
+ *
+ *         refreshGrid: function() {
+ *             this.getList().store.load();
+ *         }
+ *     });
+ *
+ * This example assumes the existence of a {@link Ext.grid.Panel Grid} on the page, which contains a single button to
+ * refresh the Grid when clicked. In our refs array, we set up a reference to the grid. There are two parts to this -
+ * the 'selector', which is a {@link Ext.ComponentQuery ComponentQuery} selector which finds any grid on the page and
+ * assigns it to the reference 'list'.
+ *
+ * By giving the reference a name, we get a number of things for free. The first is the getList function that we use in
+ * the refreshGrid method above. This is generated automatically by the Controller based on the name of our ref, which
+ * was capitalized and prepended with get to go from 'list' to 'getList'.
+ *
+ * The way this works is that the first time getList is called by your code, the ComponentQuery selector is run and the
+ * first component that matches the selector ('grid' in this case) will be returned. All future calls to getList will
+ * use a cached reference to that grid. Usually it is advised to use a specific ComponentQuery selector that will only
+ * match a single View in your application (in the case above our selector will match any grid on the page).
+ *
+ * Bringing it all together, our init function is called when the application boots, at which time we call this.control
+ * to listen to any click on a {@link Ext.button.Button button} and call our refreshGrid function (again, this will
+ * match any button on the page so we advise a more specific selector than just 'button', but have left it this way for
+ * simplicity). When the button is clicked we use out getList function to refresh the grid.
+ *
+ * You can create any number of refs and control any number of components this way, simply adding more functions to
+ * your Controller as you go. For an example of real-world usage of Controllers see the Feed Viewer example in the
+ * examples/app/feed-viewer folder in the SDK download.
+ *
+ * <u>Generated getter methods</u>
+ *
+ * Refs aren't the only thing that generate convenient getter methods. Controllers often have to deal with Models and
+ * Stores so the framework offers a couple of easy ways to get access to those too. Let's look at another example:
+ *
+ *     Ext.define('MyApp.controller.Users', {
+ *         extend: 'Ext.app.Controller',
+ *
+ *         models: ['User'],
+ *         stores: ['AllUsers', 'AdminUsers'],
+ *
+ *         init: function() {
+ *             var User = this.getUserModel(),
+ *                 allUsers = this.getAllUsersStore();
+ *
+ *             var ed = new User({name: 'Ed'});
+ *             allUsers.add(ed);
+ *         }
+ *     });
+ *
+ * By specifying Models and Stores that the Controller cares about, it again dynamically loads them from the appropriate
+ * locations (app/model/User.js, app/store/AllUsers.js and app/store/AdminUsers.js in this case) and creates getter
+ * functions for them all. The example above will create a new User model instance and add it to the AllUsers Store.
+ * Of course, you could do anything in this function but in this case we just did something simple to demonstrate the
+ * functionality.
+ *
+ * <u>Further Reading</u>
+ *
+ * For more information about writing Ext JS 4 applications, please see the
+ * [application architecture guide](#/guide/application_architecture). Also see the {@link Ext.app.Application} documentation.
+ *
+ * @docauthor Ed Spencer
+ */
+Ext.define('Ext.app.Controller', {
+
+    mixins: {
+        observable: 'Ext.util.Observable'
+    },
+
+    /**
+     * @cfg {String} id The id of this controller. You can use this id when dispatching.
+     */
+    
+    /**
+     * @cfg {String[]} models
+     * Array of models to require from AppName.model namespace. For example:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         models: ['User', 'Vehicle']
+     *     });
+     * 
+     * This is equivalent of:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         requires: ['MyApp.model.User', 'MyApp.model.Vehicle']
+     *     });
+     * 
+     */
+
+    /**
+     * @cfg {String[]} views
+     * Array of views to require from AppName.view namespace. For example:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         views: ['List', 'Detail']
+     *     });
+     * 
+     * This is equivalent of:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         requires: ['MyApp.view.List', 'MyApp.view.Detail']
+     *     });
+     * 
+     */
+
+    /**
+     * @cfg {String[]} stores
+     * Array of stores to require from AppName.store namespace. For example:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         stores: ['Users', 'Vehicles']
+     *     });
+     * 
+     * This is equivalent of:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         requires: ['MyApp.store.Users', 'MyApp.store.Vehicles']
+     *     });
+     * 
+     */
+
+    /**
+     * @cfg {Object[]} refs
+     * Array of configs to build up references to views on page. For example:
+     * 
+     *     Ext.define("MyApp.controller.Foo", {
+     *         extend: "Ext.app.Controller",
+     *         refs: [
+     *             {
+     *                 ref: 'list',
+     *                 selector: 'grid'
+     *             }
+     *         ],
+     *     });
+     * 
+     * This will add method `getList` to the controller which will internally use
+     * Ext.ComponentQuery to reference the grid component on page.
+     */
+
+    onClassExtended: function(cls, data, hooks) {
+        var className = Ext.getClassName(cls),
+            match = className.match(/^(.*)\.controller\./),
+            namespace,
+            onBeforeClassCreated,
+            requires,
+            modules,
+            namespaceAndModule;
+        
+        if (match !== null) {
+            namespace = Ext.Loader.getPrefix(className) || match[1];
+            onBeforeClassCreated = hooks.onBeforeCreated;
+            requires = [];
+            modules = ['model', 'view', 'store'];
+
+            hooks.onBeforeCreated = function(cls, data) {
+                var i, ln, module,
+                    items, j, subLn, item;
+
+                for (i = 0,ln = modules.length; i < ln; i++) {
+                    module = modules[i];
+                    namespaceAndModule = namespace + '.' + module + '.';
+
+                    items = Ext.Array.from(data[module + 's']);
+
+                    for (j = 0,subLn = items.length; j < subLn; j++) {
+                        item = items[j];
+                        // Deciding if a class name must be qualified:
+                        // 1 - if the name doesn't contains at least one dot, we must definitely qualify it
+                        // 2 - the name may be a qualified name of a known class, but:
+                        // 2.1 - in runtime, the loader may not know the class - specially in production - so we must check the class manager
+                        // 2.2 - in build time, the class manager may not know the class, but the loader does, so we check the second one
+                        //       (the loader check assures it's really a class, and not a namespace, so we can have 'Books.controller.Books',
+                        //       and requesting a controller called Books will not be underqualified)
+                        if (item.indexOf('.') !== -1 && (Ext.ClassManager.isCreated(item) || Ext.Loader.isAClassNameWithAKnownPrefix(item))) {
+                            requires.push(item);
+                        } else {
+                            requires.push(namespaceAndModule + item);
+                        }
+                    }
+                }
+
+                Ext.require(requires, Ext.Function.pass(onBeforeClassCreated, arguments, this));
+            };
+        }
+    },
+
+    /**
+     * Creates new Controller.
+     * @param {Object} config (optional) Config object.
+     */
+    constructor: function(config) {
+        this.mixins.observable.constructor.call(this, config);
+
+        Ext.apply(this, config || {});
+        this.createGetters('model', this.models);
+        this.createGetters('store', this.stores);
+        this.createGetters('view', this.views);
+
+        if (this.refs) {
+            this.ref(this.refs);
+        }
+    },
+
+    /**
+     * A template method that is called when your application boots. It is called before the
+     * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
+     * your Viewport is created.
+     *
+     * @param {Ext.app.Application} application
+     * @template
+     */
+    init: function(application) {},
+
+    /**
+     * A template method like {@link #init}, but called after the viewport is created.
+     * This is called after the {@link Ext.app.Application#launch launch} method of Application is executed.
+     *
+     * @param {Ext.app.Application} application
+     * @template
+     */
+    onLaunch: function(application) {},
+
+    createGetters: function(type, refs) {
+        type = Ext.String.capitalize(type);
+
+        var i      = 0,
+            length = (refs) ? refs.length : 0,
+            fn, ref, parts, x, numParts;
+
+        for (; i < length; i++) {
+            fn    = 'get';
+            ref   = refs[i];
+            parts = ref.split('.');
+            numParts = parts.length;
+
+            // Handle namespaced class names. E.g. feed.Add becomes getFeedAddView etc.
+            for (x = 0 ; x < numParts; x++) {
+                fn += Ext.String.capitalize(parts[x]);
+            }
+
+            fn += type;
+
+            if (!this[fn]) {
+                this[fn] = Ext.Function.pass(this['get' + type], [ref], this);
+            }
+            // Execute it right away
+            this[fn](ref);
+        }
+    },
+
+    ref: function(refs) {
+        refs = Ext.Array.from(refs);
+        
+        var me = this,
+            i = 0,
+            length = refs.length,
+            info, ref, fn;
+
+        for (; i < length; i++) {
+            info = refs[i];
+            ref  = info.ref;
+            fn   = 'get' + Ext.String.capitalize(ref);
+
+            if (!me[fn]) {
+                me[fn] = Ext.Function.pass(me.getRef, [ref, info], me);
+            }
+            me.references = me.references || [];
+            me.references.push(ref.toLowerCase());
+        }
+    },
+
+    addRef: function(ref) {
+        return this.ref([ref]);
+    },
+
+    getRef: function(ref, info, config) {
+        this.refCache = this.refCache || {};
+        info = info || {};
+        config = config || {};
+
+        Ext.apply(info, config);
+
+        if (info.forceCreate) {
+            return Ext.ComponentManager.create(info, 'component');
+        }
+
+        var me = this,
+            cached = me.refCache[ref];
+
+        if (!cached) {
+            me.refCache[ref] = cached = Ext.ComponentQuery.query(info.selector)[0];
+            if (!cached && info.autoCreate) {
+                me.refCache[ref] = cached = Ext.ComponentManager.create(info, 'component');
+            }
+            if (cached) {
+                cached.on('beforedestroy', function() {
+                    me.refCache[ref] = null;
+                });
+            }
+        }
+
+        return cached;
+    },
+
+    hasRef: function(ref) {
+        return this.references && this.references.indexOf(ref.toLowerCase()) !== -1;
+    },
+
+    /**
+     * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an
+     * object containing component paths mapped to a hash of listener functions.
+     *
+     * In the following example the `updateUser` function is mapped to to the `click`
+     * event on a button component, which is a child of the `useredit` component.
+     *
+     *     Ext.define('AM.controller.Users', {
+     *         init: function() {
+     *             this.control({
+     *                 'useredit button[action=save]': {
+     *                     click: this.updateUser
+     *                 }
+     *             });
+     *         },
+     *
+     *         updateUser: function(button) {
+     *             console.log('clicked the Save button');
+     *         }
+     *     });
+     *
+     * See {@link Ext.ComponentQuery} for more information on component selectors.
+     *
+     * @param {String/Object} selectors If a String, the second argument is used as the
+     * listeners, otherwise an object of selectors -> listeners is assumed
+     * @param {Object} listeners
+     */
+    control: function(selectors, listeners) {
+        this.application.control(selectors, listeners, this);
+    },
+
+    /**
+     * Returns instance of a {@link Ext.app.Controller controller} with the given name.
+     * When controller doesn't exist yet, it's created.
+     * @param {String} name
+     * @return {Ext.app.Controller} a controller instance.
+     */
+    getController: function(name) {
+        return this.application.getController(name);
+    },
+
+    /**
+     * Returns instance of a {@link Ext.data.Store Store} with the given name.
+     * When store doesn't exist yet, it's created.
+     * @param {String} name
+     * @return {Ext.data.Store} a store instance.
+     */
+    getStore: function(name) {
+        return this.application.getStore(name);
+    },
+
+    /**
+     * Returns a {@link Ext.data.Model Model} class with the given name.
+     * A shorthand for using {@link Ext.ModelManager#getModel}.
+     * @param {String} name
+     * @return {Ext.data.Model} a model class.
+     */
+    getModel: function(model) {
+        return this.application.getModel(model);
+    },
+
+    /**
+     * Returns a View class with the given name.  To create an instance of the view,
+     * you can use it like it's used by Application to create the Viewport:
+     *
+     *     this.getView('Viewport').create();
+     *
+     * @param {String} name
+     * @return {Ext.Base} a view class.
+     */
+    getView: function(view) {
+        return this.application.getView(view);
+    }
+});