[extjs.git] / extjs / packages / core / src / app / Controller.js

/**\r
 * Controllers are the glue that binds an application together. That said, their main \r
 * purpose is to listen for events (usually from views) and take some action. Here's how \r
 * we might create a Controller to manage Users:\r
 *\r
 *      Ext.define('MyApp.controller.Users', {\r
 *          extend: 'Ext.app.Controller',\r
 *\r
 *          init: function() {\r
 *              console.log('Initialized Users! This happens before ' +\r
 *                          'the Application launch() function is called');\r
 *          }\r
 *      });\r
 *\r
 * The init function is a special method that is called when your application boots. It is \r
 * called before the {@link Ext.app.Application Application}'s launch function is executed. \r
 * This creates an area you can run code prior to Viewport creation.\r
 *\r
 * The controller's {@link #method-control} function\r
 * makes it easy to listen to events on your view classes and take some action with a \r
 * handler function. Let's update our Users controller to tell us when the panel is \r
 * rendered:\r
 *\r
 *      Ext.define('MyApp.controller.Users', {\r
 *          extend: 'Ext.app.Controller',\r
 *\r
 *          control: {\r
 *              'viewport > panel': {\r
 *                  render: 'onPanelRendered'\r
 *              }\r
 *          }\r
 *\r
 *          onPanelRendered: function() {\r
 *              console.log('The panel was rendered');\r
 *          }\r
 *      });\r
 *\r
 * The {@link Ext.app.BaseController#method-control control method} has now set up \r
 * listeners on views in our application. The control method uses the ComponentQuery \r
 * engine to quickly and easily get references to components on the page. If you are not \r
 * familiar with ComponentQuery yet, be sure to check out the \r
 * {@link Ext.ComponentQuery documentation}. In brief, it allows us to pass a \r
 * CSS-like selector that will find every matching component on the page.\r
 *\r
 * In our init function above, we supplied 'viewport > panel', which translates to "find me \r
 * every Panel that is a direct child of a Viewport". We then supplied an object that maps \r
 * event names (just 'render' in this case) to handler functions. In short, whenever \r
 * a component that matches our selector fires a 'render' event, our\r
 * onPanelRendered function is called.\r
 *\r
 * ## Event domains\r
 *\r
 * In Ext JS 4.2, we introduced the concept of event domains. In terms of MVC, an event \r
 * domain is one or more base classes that fire events to which a Controller wants to \r
 * listen. Besides Component event domain that encompass {@link Ext.Component}-descended \r
 * Views, Controllers now can listen to events from data Stores, Ext Direct Providers, \r
 * other Controllers, and Ext.GlobalEvents. This feature provides a way to communicate \r
 * between parts of the whole application without the need to bind controllers together \r
 * tightly, and allows to develop and test application parts in isolation.\r
 *\r
 * See usage examples in {@link #method-listen} method documentation.\r
 *\r
 * ## Using refs\r
 *\r
 * One of the most useful parts of Controllers is the ref system. These use \r
 * {@link Ext.ComponentQuery} to make it really easy to get references to Views on your \r
 * page. Let's look at an example of this now:\r
 *\r
 *      Ext.define('MyApp.controller.Users', {\r
 *          extend: 'Ext.app.Controller',\r
 *          \r
 *          refs: [{\r
 *              ref: 'list',\r
 *              selector: 'grid'\r
 *          }],\r
 *          \r
 *          control: {\r
 *              'button': {\r
 *                  click: 'refreshGrid'\r
 *              }\r
 *          },\r
 *          \r
 *          refreshGrid: function() {\r
 *              this.getList().store.load();\r
 *          }\r
 *      });\r
 *\r
 * This example assumes the existence of a {@link Ext.grid.Panel Grid} on the page, which \r
 * contains a single button to refresh the Grid when clicked. In our refs array, we set up \r
 * a reference to the grid. There are two parts to this - the 'selector', which is a \r
 * {@link Ext.ComponentQuery ComponentQuery} selector which finds any grid on the page and\r
 * assigns it to the reference 'list'.\r
 *\r
 * By giving the reference a name, we get a number of things for free. The first is the \r
 * getList function that we use in the refreshGrid method above. This is generated \r
 * automatically by the Controller based on the name of our ref, which was capitalized and \r
 * prepended with get to go from 'list' to 'getList'.\r
 *\r
 * The way this works is that the first time getList is called by your code, the \r
 * ComponentQuery selector is run and the first component that matches the selector \r
 * ('grid' in this case) will be returned. All future calls to getList will use a cached \r
 * reference to that grid. Usually it is advised to use a specific ComponentQuery selector \r
 * that will only match a single View in your application (in the case above our selector \r
 * will match any grid on the page).\r
 *\r
 * Bringing it all together, we configure control\r
 * to listen to any click on a {@link Ext.button.Button button} and call our refreshGrid \r
 * function (again, this will match any button on the page so we advise a more specific \r
 * selector than just 'button', but have left it this way for simplicity). When the button \r
 * is clicked we use out getList function to refresh the grid.\r
 *\r
 * You can create any number of refs and control any number of components this way, simply \r
 * adding more functions to your Controller as you go. For an example of real-world usage \r
 * of Controllers see the Feed Viewer example in the examples/app/feed-viewer folder in \r
 * the SDK download.\r
 *\r
 * ## Generated getter methods\r
 *\r
 * Refs aren't the only thing that generate convenient getter methods. Controllers often \r
 * have to deal with Models and Stores so the framework offers a couple of easy ways to \r
 * get access to those too. Let's look at another example:\r
 *\r
 *      Ext.define('MyApp.controller.Users', {\r
 *          extend: 'Ext.app.Controller',\r
 *\r
 *          models: ['User'],\r
 *          stores: ['AllUsers', 'AdminUsers'],\r
 *\r
 *          init: function() {\r
 *              var User, allUsers, ed;\r
 *              \r
 *              User = this.getUserModel();\r
 *              allUsers = this.getAllUsersStore();\r
 *\r
 *              ed = new User({ name: 'Ed' });\r
 *              allUsers.add(ed);\r
 *          }\r
 *      });\r
 *\r
 * By specifying Models and Stores that the Controller cares about, it again dynamically \r
 * loads them from the appropriate locations (app/model/User.js, app/store/AllUsers.js and \r
 * app/store/AdminUsers.js in this case) and creates getter functions for them all. The \r
 * example above will create a new User model instance and add it to the AllUsers Store.\r
 * Of course, you could do anything in this function but in this case we just did \r
 * something simple to demonstrate the functionality.\r
 *\r
 * ## Further Reading\r
 *\r
 * For more information about writing Ext JS 5 applications, please see the\r
 * [Application Architecture](../../../application_architecture/application_architecture.html). \r
 * Also see the {@link Ext.app.Application} documentation.\r
 */\r
Ext.define('Ext.app.Controller', {\r
    extend: 'Ext.app.BaseController',\r
    requires: [\r
        'Ext.app.Util',\r
        'Ext.data.StoreManager',\r
        'Ext.ComponentManager',\r
        'Ext.app.domain.Component',\r
        'Ext.app.domain.Store',\r
        'Ext.app.route.Router'\r
    ],\r
\r
    statics: {\r
        strings: {\r
            model: {\r
                getter: 'getModel',\r
                upper: 'Model'\r
            },\r
\r
            view: {\r
                getter: 'getView',\r
                upper: 'View'\r
            },\r
\r
            controller: {\r
                getter: 'getController',\r
                upper: 'Controller'\r
            },\r
\r
            store: {\r
                getter: 'getStore',\r
                upper: 'Store'\r
            },\r
\r
            profile: {\r
                getter: 'getProfile',\r
                upper: 'Profiles'\r
            }\r
        },\r
\r
        controllerRegex: /^(.*)\.controller\./,\r
        profileRegex: /^(.*)\.profile\./,\r
\r
        createGetter: function(baseGetter, name) {\r
            return function () {\r
                return this[baseGetter](name);\r
            };\r
        },\r
\r
        getGetterName: function(name, kindUpper) {\r
            var fn       = 'get',\r
                parts    = name.split('.'),\r
                numParts = parts.length,\r
                index;\r
\r
            // Handle namespaced class names. E.g. feed.Add becomes getFeedAddView etc.\r
            for (index = 0; index < numParts; index++) {\r
                fn += Ext.String.capitalize(parts[index]);\r
            }\r
\r
            fn += kindUpper;\r
            \r
            return fn;\r
        },\r
\r
        resolveNamespace: function(cls, data) {\r
            var Controller = Ext.app.Controller,\r
                namespaceRe = cls.prototype.isProfile ? Controller.profileRegex : Controller.controllerRegex,\r
                className, namespace, match;\r
            /*\r
             * Namespace resolution is tricky business: we should know what namespace\r
             * this Controller descendant belongs to, or model/store/view dependency\r
             * resolution will be either ambiguous or plainly not possible. To avoid\r
             * guessing games we try to look for a forward hint ($namespace) that\r
             * Application class sets when its onClassExtended gets processed; if that\r
             * fails we try to deduce namespace from class name.\r
             *\r
             * Note that for Ext.app.Application, Controller.onClassExtended gets executed\r
             * *before* Application.onClassExtended so we have to delay namespace handling\r
             * until after Application.onClassExtended kicks in, hence it is done in this hook.\r
             */\r
            className = Ext.getClassName(cls);\r
            namespace = data.$namespace || data.namespace ||\r
                Ext.app.getNamespace(className) ||\r
                ((match = namespaceRe.exec(className)) && match[1]);\r
\r
            //<debug>\r
            if (!namespace) {\r
                Ext.log.warn("Missing namespace for " + className + ", please define it "+\r
                    "in namespaces property of your Application class.");\r
            }\r
            //</debug>\r
\r
            return namespace;\r
        },\r
\r
        /**\r
         * This method is called like so:\r
         *\r
         *      Ext.app.Controller.processDependencies(proto, requiresArray, 'MyApp', 'model', [\r
         *          'User',\r
         *          'Item',\r
         *          'Foo@Common.model',\r
         *          'Bar.Baz@Common.model'\r
         *      ]);\r
         *\r
         * Required dependencies are added to requiresArray.\r
         *\r
         * @private\r
         */\r
        processDependencies: function(cls, requires, namespace, kind, names, profileName) {\r
            if (!names || !names.length) {\r
                return;\r
            }\r
\r
            var me = this,\r
                strings = me.strings[kind],\r
                o, absoluteName, shortName, name, j, subLn, getterName, getter;\r
                \r
             if (!Ext.isArray(names)) {\r
                 names = [names];\r
             }\r
\r
            for (j = 0, subLn = names.length; j < subLn; j++) {\r
                name = names[j];\r
                o = me.getFullName(name, kind, namespace, profileName);\r
                // Update the name in the array to be the absolute name\r
                names[j] = absoluteName = o.absoluteName;\r
                shortName = o.shortName;\r
\r
                requires.push(absoluteName);\r
                getterName = me.getGetterName(shortName, strings.upper);\r
\r
                if (!cls[getterName]) {\r
                    cls[getterName] = getter = me.createGetter(strings.getter, name);\r
                }\r
                //<debug>\r
                else if (getterName === 'getMainView') {\r
                    Ext.log.warn('Cannot have a view named \'Main\' - getter conflicts with mainView config.')\r
                }\r
                //</debug>\r
\r
                // Application class will init the controller getters\r
                if (getter && kind !== 'controller') {\r
                    // This marker allows the constructor to easily/cheaply identify the\r
                    // generated getter methods since they all need to be called to get\r
                    // things initialized. We use a property name that deliberately does\r
                    // not work with dot-access to reduce any chance of collision.\r
                    getter['Ext.app.getter'] = true;\r
                }\r
            }\r
        },\r
\r
        getFullName: function(name, kind, namespace, profileName) {\r
            var shortName = name,\r
                sep, absoluteName;\r
\r
            if ((sep = name.indexOf('@')) > 0) {\r
                // The unambiguous syntax is Model@Name.space (or "space.Model@Name")\r
                // which contains both the short name ("Model" or "space.Model") and\r
                // the full name (Name.space.Model).\r
                //\r
                shortName    = name.substring(0, sep); // "Model"\r
                absoluteName = name.substring(sep + 1) + '.' + shortName; //  ex: "Name.space.Model"\r
            }\r
            // Deciding if a class name must be qualified:\r
            //\r
            // 1 - if the name doesn't contain a dot, we must qualify it\r
            //\r
            // 2 - the name may be a qualified name of a known class, but:\r
            //\r
            // 2.1 - in runtime, the loader may not know the class - specially in\r
            //       production - so we must check the class manager\r
            //\r
            // 2.2 - in build time, the class manager may not know the class, but\r
            //       the loader does, so we check the second one (the loader check\r
            //       assures it's really a class, and not a namespace, so we can\r
            //       have 'Books.controller.Books', and requesting a controller\r
            //       called Books will not be underqualified)\r
            //\r
            else if (name.indexOf('.') > 0 && (Ext.ClassManager.isCreated(name) ||\r
                     this.hasRegisteredPrefix(name))) {\r
                absoluteName = name;\r
            }\r
            else {\r
                //<debug>\r
                if (!namespace) {\r
                    Ext.log.warn("Cannot find namespace for " + kind + " " + name + ", " +\r
                                 "assuming it is fully qualified class name");\r
                }\r
                //</debug>\r
\r
                if (namespace) {\r
                    absoluteName = namespace + '.' + kind + '.' +\r
                                    (profileName ? profileName + '.' + name : name);\r
                    shortName    = name;\r
                }\r
                else {\r
                    absoluteName = name;\r
                }\r
            }\r
\r
            return {\r
                absoluteName: absoluteName,\r
                shortName:    shortName\r
            };\r
        },\r
\r
        hasRegisteredPrefix: function (className) {\r
            var inventory = Ext.ClassManager,\r
                prefix = inventory.getPrefix(className);\r
\r
            // It's a class if className is not equal to any known namespace\r
            return prefix && prefix !== className;\r
        }\r
    },\r
\r
    // @cmd-auto-dependency {aliasPrefix : "model.", mvc : true, blame: "all"}\r
    /**\r
     * @cfg {String/String[]} models\r
     * Array of models to require from AppName.model namespace. For example:\r
     *\r
     *      Ext.define("MyApp.controller.Foo", {\r
     *          extend: "Ext.app.Controller",\r
     *          models: ['User', 'Vehicle']\r
     *      });\r
     *\r
     * This is equivalent to:\r
     *\r
     *      Ext.define("MyApp.controller.Foo", {\r
     *          extend: "Ext.app.Controller",\r
     *          requires: ['MyApp.model.User', 'MyApp.model.Vehicle'],\r
     *          \r
     *          getUserModel: function() {\r
     *              return this.getModel("User");\r
     *          },\r
     *          \r
     *          getVehicleModel: function() {\r
     *              return this.getModel("Vehicle");\r
     *          }\r
     *      });\r
     *\r
     * **Note:** If the model has a different namespace than that of the \r
     * application you will need to specify the full class name as well as define a path \r
     * in the {@link Ext.Loader#cfg-paths Loader's paths} config or \r
     * {@link Ext.Loader#method-setPath setPath} method.\r
     */\r
    models: null,\r
\r
    // @cmd-auto-dependency {aliasPrefix: "view.", mvc: true, blame: "all"}\r
    /**\r
     * @cfg {String/String[]} views\r
     * Array of views to require from AppName.view namespace and to generate getter methods for.\r
     * For example:\r
     *\r
     *      Ext.define("MyApp.controller.Foo", {\r
     *          extend: "Ext.app.Controller",\r
     *          views: ['List', 'Detail']\r
     *      });\r
     *\r
     * This is equivalent to:\r
     *\r
     *      Ext.define("MyApp.controller.Foo", {\r
     *          extend: "Ext.app.Controller",\r
     *          requires: ['MyApp.view.List', 'MyApp.view.Detail'],\r
     *          \r
     *          getListView: function() {\r
     *              return this.getView("List");\r
     *          },\r
     *          \r
     *          getDetailView: function() {\r
     *              return this.getView("Detail");\r
     *          }\r
     *      });\r
     * \r
     * **Note:** If the view has a different namespace than that of the \r
     * application you will need to specify the full class name as well as define a path \r
     * in the {@link Ext.Loader#cfg-paths Loader's paths} config or \r
     * {@link Ext.Loader#method-setPath setPath} method.\r
     */\r
    views: null,\r
\r
    // @cmd-auto-dependency {aliasPrefix: "store.", mvc: true, blame: "all"}\r
    /**\r
     * @cfg {String/String[]} stores\r
     * Array of stores to require from AppName.store namespace and to generate getter methods for.\r
     * For example:\r
     *\r
     *      Ext.define("MyApp.controller.Foo", {\r
     *          extend: "Ext.app.Controller",\r
     *          stores: ['Users', 'Vehicles']\r
     *      });\r
     *\r
     * This is equivalent to:\r
     *\r
     *      Ext.define("MyApp.controller.Foo", {\r
     *          extend: "Ext.app.Controller",\r
     *         \r
     *          requires: [\r
     *              'MyApp.store.Users',\r
     *              'MyApp.store.Vehicles'\r
     *          ]\r
     *         \r
     *          getUsersStore: function() {\r
     *              return this.getStore("Users");\r
     *          },\r
     *\r
     *          getVehiclesStore: function() {\r
     *              return this.getStore("Vehicles");\r
     *          }\r
     *      });\r
     * \r
     * **Note:** If the store has a different namespace than that of the \r
     * application you will need to specify the full class name as well as define a path \r
     * in the {@link Ext.Loader#cfg-paths Loader's paths} config or \r
     * {@link Ext.Loader#method-setPath setPath} method.\r
     */\r
    stores: null,\r
\r
    // @cmd-auto-dependency {aliasPrefix: "controller.", mvc: true, blame: "all"}\r
    controllers: null,\r
\r
    config : {\r
        /**\r
         * @cfg {Ext.app.Application} application The {@link Ext.app.Application} for this controller accessible via the getApplication method.\r
         * @accessor\r
         * @readonly\r
         */\r
        application: null,\r
        \r
        /**\r
         * @cfg {Object/Object[]} refs\r
         * @accessor\r
         *\r
         * The refs config creates a getter method on the controller that internally \r
         * uses Ext.ComponentQuery to fetch the component instance using the configured \r
         * selector.  The following example will add the `getList` method to \r
         * the controller and will return the first component in the application \r
         * hierarchy with an xtype of "grid".  By default, *undefined* will be returned \r
         * when the query does not locate the target component.\r
         *\r
         *     Ext.define('MyApp.controller.Foo', {\r
         *         extend: 'Ext.app.Controller',\r
         *         \r
         *         refs: [{\r
         *             ref: 'list',\r
         *             selector: 'grid'\r
         *         }]\r
         *     });\r
         *\r
         * The following fields may be used in the ref definition:\r
         *\r
         * - `ref` - name of the reference.\r
         * - `selector` - Ext.ComponentQuery selector to access the component.\r
         * - `autoCreate` - True to create the component automatically if not found on \r
         * page.\r
         * - `forceCreate` - True to force the creation of the component every time \r
         * reference is accessed (when `get<REFNAME>` is called).\r
         * - `xtype` - Used to create the component by its xtype with `autoCreate` or \r
         * `forceCreate`. If you don't provide `xtype`, an Ext.Component instance will \r
         * be created.\r
         * \r
         * The following example will create a `getList` and `getUser` method on the \r
         * controller.\r
         * \r
         *     Ext.define('MyApp.controller.Foo', {\r
         *         extend: 'Ext.app.Controller',\r
         *     \r
         *         refs: [{\r
         *             list: 'grid',\r
         *             user: {\r
         *                 autoCreate: true,\r
         *                 selector: 'form',\r
         *                 xtype: 'form'\r
         *             }\r
         *         }]\r
         *     });\r
         */\r
        refs: null,\r
\r
        active: true,\r
\r
        /**\r
         * @private\r
         */\r
        moduleClassName: null\r
    },\r
\r
    onClassExtended: function(cls, data, hooks) {\r
        var onBeforeClassCreated = hooks.onBeforeCreated;\r
\r
        hooks.onBeforeCreated = function(cls, data) {\r
            var Controller = Ext.app.Controller,\r
                requires   = [],\r
                namespace, proto;\r
\r
            proto = cls.prototype;\r
\r
            namespace = Controller.resolveNamespace(cls, data);\r
\r
            if (namespace) {\r
                proto.$namespace = namespace;\r
            }\r
\r
            Controller.processDependencies(proto, requires, namespace, 'model',      data.models);\r
            Controller.processDependencies(proto, requires, namespace, 'view',       data.views);\r
            Controller.processDependencies(proto, requires, namespace, 'store',      data.stores);\r
            Controller.processDependencies(proto, requires, namespace, 'controller', data.controllers);\r
\r
            Ext.require(requires, Ext.Function.pass(onBeforeClassCreated, arguments, this));\r
        };\r
    },\r
\r
    /**\r
     * Creates new Controller.\r
     *\r
     * @param {Object} [config] Configuration object.\r
     */\r
    constructor: function(config) {\r
        this.initAutoGetters();\r
        this.callParent(arguments);\r
    },\r
\r
    /**\r
     * @private\r
     * Takes either an object and transforms it into an array. The following are valid refs values:\r
     *\r
     *     refs: {\r
     *         myComponent: 'container'\r
     *     }\r
     *\r
     *     refs: {\r
     *         myComponent: {\r
     *             selector: 'container'\r
     *         }\r
     *     }\r
     *\r
     *     refs: [\r
     *         {\r
     *             ref: 'myComponent',\r
     *             selector: 'container'\r
     *         }\r
     *     ]\r
     *\r
     * @param {Array|Object} refs The refs to normalize\r
     * @param {Array} newRefs An array to place the normalized refs on to\r
     * @return {Array} The normalized array of refs\r
     */\r
    normalizeRefs: function(refs) {\r
        var me = this,\r
            newRefs = [];\r
\r
        if (refs) {\r
            if (Ext.isObject(refs)) {\r
                Ext.Object.each(refs, function(key, value) {\r
                    if (Ext.isString(value)) {\r
                        value = {\r
                            selector : value\r
                        };\r
                    }\r
\r
                    value.ref = key;\r
\r
                    newRefs.push(value);\r
                });\r
            } else if (Ext.isArray(refs)) {\r
                newRefs = Ext.Array.merge(newRefs, refs);\r
            }\r
        }\r
\r
        refs = me.refs;\r
\r
        if (refs) {\r
            me.refs = null;\r
\r
            refs = me.normalizeRefs(refs);\r
\r
            if (refs) {\r
                newRefs = Ext.Array.merge(newRefs, refs);\r
            }\r
        }\r
\r
        return newRefs;\r
    },\r
\r
    /**\r
     * Returns a map of reference names to selectors\r
     * @private\r
     */\r
    getRefMap: function() {\r
        var me = this,\r
            refMap = me._refMap,\r
            refs, ref, ln, i;\r
\r
        if (!refMap) {\r
            refs = me.getRefs();\r
            refMap = me._refMap = {};\r
\r
            if (refs) {\r
                for (i = 0, ln = refs.length; i < ln; i++) {\r
                    ref = refs[i];\r
                    refMap[ref.ref] = ref.selector;\r
                }\r
            }\r
        }\r
\r
        return refMap;\r
    },\r
\r
    applyRefs: function(refs) {\r
        return this.normalizeRefs(Ext.clone(refs));\r
    },\r
\r
    /**\r
     * @param {Object} refs The refs to pass to the {@link #ref} method.\r
     * @private\r
     */\r
    updateRefs: function(refs) {\r
        if (refs) {\r
            this.ref(refs);\r
        }\r
    },\r
\r
    initAutoGetters: function() {\r
        var proto = this.self.prototype,\r
            prop, fn;\r
\r
        for (prop in proto) {\r
            fn = proto[prop];\r
\r
            // Look for the marker placed on the getters by processDependencies so that\r
            // we can know what to call cheaply:\r
            if (fn && fn['Ext.app.getter']) {\r
                fn.call(this);\r
            }\r
        }\r
    },\r
\r
    doInit: function(app) {\r
        var me = this;\r
\r
        if (!me._initialized) {\r
            me.init(app);\r
            me._initialized = true;\r
        }\r
    },\r
    \r
    finishInit: function(app) {\r
        var me = this,\r
            controllers = me.controllers,\r
            controller, i, l;\r
\r
        if (me._initialized && controllers && controllers.length) {\r
            for (i = 0, l = controllers.length; i < l; i++) {\r
                controller = me.getController(controllers[i]);\r
                controller.finishInit(app);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * @method\r
     *\r
     * A template method that is called when your application boots. It is called before the\r
     * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point\r
     * to run any code before your Viewport is created.\r
     *\r
     * @param {Ext.app.Application} application\r
     *\r
     * @template\r
     */\r
    init: Ext.emptyFn,\r
\r
    /**\r
     * @method\r
     *\r
     * A template method like {@link #init}, but called after the viewport is created.\r
     * This is called after the {@link Ext.app.Application#launch launch} method of Application\r
     * is executed.\r
     *\r
     * @param {Ext.app.Application} application\r
     *\r
     * @template\r
     */\r
    onLaunch: Ext.emptyFn,\r
    \r
    /**\r
     * Allow the controller to resume receiving events from the event bus.\r
     * Routes will also be able to begin firing on this controller.\r
     * Also see {@link #deactivate}.\r
     */\r
    activate: function() {\r
        this.setActive(true);\r
    },\r
    \r
    /**\r
     * Prevent this controller from receiving events from the event bus.\r
     * Routes will also not be triggered on inactive controllers unless\r
     * the {@link Ext.app.route.Route#allowInactive} flag is set.\r
     * Also see {@link #activate}.\r
     */\r
    deactivate: function() {\r
        this.setActive(false);\r
    },\r
    \r
    /**\r
     * Checks if this controller is active. See {@link #activate} & \r
     * {@link #deactivate}.\r
     * @return {Boolean} `true` if this controller is active.\r
     */\r
    isActive: function() {\r
        return this.getActive();\r
    },\r
\r
    ref: function(refs) {\r
        var me = this,\r
            i = 0,\r
            length = refs.length,\r
            info, ref, fn;\r
\r
        refs = Ext.Array.from(refs);\r
\r
        me.references = me.references || [];\r
\r
        for (; i < length; i++) {\r
            info = refs[i];\r
            ref  = info.ref;\r
            fn   = 'get' + Ext.String.capitalize(ref);\r
\r
            if (!me[fn]) {\r
                me[fn] = Ext.Function.pass(me.getRef, [ref, info], me);\r
            }\r
            me.references.push(ref.toLowerCase());\r
        }\r
    },\r
\r
    /**\r
     * Registers one or more {@link #refs references}.\r
     *\r
     * @param {Object/Object[]} refs\r
     */\r
    addRef: function(refs) {\r
        this.ref(refs);\r
    },\r
\r
    getRef: function(ref, info, config) {\r
        var me = this,\r
            refCache = me.refCache || (me.refCache = {}),\r
            cached = refCache[ref];\r
\r
        info = info || {};\r
        config = config || {};\r
\r
        Ext.apply(info, config);\r
\r
        if (info.forceCreate) {\r
            return Ext.ComponentManager.create(info, 'component');\r
        }\r
\r
        if (!cached) {\r
            if (info.selector) {\r
                refCache[ref] = cached = Ext.ComponentQuery.query(info.selector)[0];\r
            }\r
            \r
            if (!cached && info.autoCreate) {\r
                refCache[ref] = cached = Ext.ComponentManager.create(info, 'component');\r
            }\r
            \r
            if (cached) {\r
                cached.on('beforedestroy', function() {\r
                    refCache[ref] = null;\r
                });\r
            }\r
        }\r
\r
        return cached;\r
    },\r
\r
    /**\r
     * Returns `true` if a {@link #refs reference} is registered.\r
     *\r
     * @param {String} ref The name of the ref to check for.\r
     * @return {Boolean}\r
     */\r
    hasRef: function(ref) {\r
        var references = this.references;\r
        return references && Ext.Array.indexOf(references, ref.toLowerCase()) !== -1;\r
    },\r
\r
    /**\r
     * Returns instance of a {@link Ext.app.Controller Controller} with the given id.\r
     * When controller doesn't exist yet, it's created. Note that this method depends\r
     * on Application instance and will return undefined when Application is not\r
     * accessible. The only exception is when this Controller instance's id is requested;\r
     * in that case we always return the instance even if Application is no available.\r
     *\r
     * @param {String} id\r
     *\r
     * @return {Ext.app.Controller} controller instance or undefined.\r
     */\r
    getController: function(id) {\r
        var app = this.getApplication();\r
\r
        if (id === this.getId()) {\r
            return this;\r
        }\r
\r
        return app && app.getController(id);\r
    },\r
\r
    /**\r
     * Returns instance of a {@link Ext.data.Store Store} with the given name.\r
     * When store doesn't exist yet, it's created.\r
     *\r
     * @param {String} name\r
     *\r
     * @return {Ext.data.Store} a store instance.\r
     */\r
    getStore: function(name) {\r
        var storeId, store;\r
\r
        storeId = (name.indexOf('@') === -1) ? name : name.split('@')[0];\r
        store   = Ext.StoreManager.get(storeId);\r
\r
        if (!store) {\r
            name = Ext.app.Controller.getFullName(name, 'store', this.$namespace);\r
\r
            if (name) {\r
                store = Ext.create(name.absoluteName, {\r
                    // Use id here. If the store has a configured storeId, \r
                    // that will take precedence\r
                    id: storeId\r
                });\r
            }\r
        }\r
\r
        return store;\r
    },\r
\r
    /**\r
     * Returns a {@link Ext.data.Model Model} class with the given name.\r
     *\r
     * @param {String} name\r
     * @return {Ext.Class} A class ultimately derived from `Ext.data.Model`.\r
     */\r
    getModel: function(model) {\r
        var name = Ext.app.Controller.getFullName(model, 'model', this.$namespace),\r
            ret = Ext.ClassManager.get(name.absoluteName);\r
\r
        if (!ret) {\r
            ret = Ext.data.schema.Schema.lookupEntity(model);\r
        }\r
\r
        return ret;\r
    },\r
\r
    /**\r
     * Returns instance of a {@link Ext.app.Profile Profile} with the given name.\r
     *\r
     * @param {String} name\r
     *\r
     * @return {String} a profile instance.\r
     */\r
    getProfile: function(name) {\r
        name = Ext.app.Controller.getFullName(name, 'profile', this.$namespace);\r
        return name;\r
    },\r
\r
    /**\r
     * Returns a View class with the given name.  To create an instance of the view,\r
     * you can use it like it's used by Application to create the Viewport:\r
     *\r
     *     this.getView('Viewport').create();\r
     *\r
     * @param {String} view\r
     *\r
     * @return {Ext.Base} a view class.\r
     */\r
    getView: function(view) {\r
        var name = Ext.app.Controller.getFullName(view, 'view', this.$namespace);\r
        return name && Ext.ClassManager.get(name.absoluteName);\r
    },\r
\r
    ensureId: function() {\r
        var id = this.getId();\r
            \r
        if (!id) {\r
            this.setId(this.getModuleClassName(this.$className, 'controller'));\r
        }    \r
    },\r
    \r
    destroy: function(destroyRefs, /* private */ fromApp) {\r
        var me = this,\r
            app = me.application,\r
            refCache, ref;\r
\r
        if (!fromApp && app) {\r
            app.unregister(me);\r
        }\r
        \r
        me.application = null;\r
        \r
        if (destroyRefs) {\r
            // Possible destroy stores here too?\r
            refCache = me.refCache;\r
            for (ref in refCache) {\r
                if (refCache.hasOwnProperty(ref)) {\r
                    Ext.destroy(refCache[ref]);\r
                }\r
            }\r
        }\r
        me.callParent();\r
    }\r
});\r