add extjs 6.0.1 sources

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

/**\r
 * @protected\r
 * @class Ext.app.BaseController\r
 * Base class for Controllers.\r
 * \r
 */\r
Ext.define('Ext.app.BaseController', {\r
    requires: [\r
        'Ext.app.EventBus',\r
        'Ext.app.domain.Global'\r
    ],\r
    \r
    uses: [\r
        'Ext.app.domain.Controller'\r
    ],\r
\r
    mixins: ['Ext.mixin.Observable'],\r
\r
    isController: true,\r
\r
    config : {\r
        /**\r
         * @cfg {String} id The id of this controller. You can use this id when dispatching.\r
         * \r
         * For an example of dispatching, see the examples under the \r
         * {@link Ext.app.Controller#cfg-listen listen} config.\r
         *\r
         * If an id is not explicitly set, it will default to the controller's full classname.\r
         * \r
         * @accessor\r
         */\r
        id: null,\r
       \r
        /**\r
         * @cfg {Object} control\r
         * @accessor\r
         *\r
         * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an\r
         * object containing component paths mapped to a hash of listener functions.  \r
         * The function value may also be a string matching the name of a method on the \r
         * controller.\r
         *\r
         * In the following example the `updateUser` function is mapped to to the `click`\r
         * event on a button component, which is a child of the `useredit` component.\r
         *\r
         *      Ext.define('MyApp.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          control: {\r
         *              'useredit button[action=save]': {\r
         *                  click: 'updateUser'\r
         *              }\r
         *          },\r
         *\r
         *          updateUser: function(button) {\r
         *              console.log('clicked the Save button');\r
         *          }\r
         *      });\r
         *\r
         * The method you pass to the listener will automatically be resolved on the controller.\r
         * In this case, the `updateUser` method that will get executed on the `button` `click`\r
         * event will resolve to the `updateUser` method on the controller,\r
         *\r
         * See {@link Ext.ComponentQuery} for more information on component selectors.\r
         */\r
\r
        control: null,\r
\r
        /**\r
         * @cfg {Object} listen\r
         * @accessor\r
         *\r
         * Adds listeners to different event sources (also called "event domains"). The\r
         * primary event domain is that of components, but there are also other event domains:\r
         * {@link Ext.app.domain.Global Global} domain that intercepts events fired from\r
         * {@link Ext.GlobalEvents} Observable instance, \r
         * {@link Ext.app.domain.Controller Controller} domain can be used to listen to events \r
         * fired by other Controllers, {@link Ext.app.domain.Store Store} domain gives access to \r
         * Store events, and {@link Ext.app.domain.Direct Direct} domain can be used with \r
         * Ext Direct Providers to listen to their events.\r
         *\r
         * To listen to "bar" events fired by a controller with id="foo":\r
         *\r
         *      Ext.define('AM.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          listen: {\r
         *              controller: {\r
         *                  '#foo': {\r
         *                      bar: 'onFooBar'\r
         *                  }\r
         *              }\r
         *          }\r
         *      });\r
         *\r
         * To listen to "bar" events fired by any controller, and "baz" events\r
         * fired by Store with storeId="baz":\r
         *\r
         *      Ext.define('AM.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          listen: {\r
         *              controller: {\r
         *                  '*': {\r
         *                      bar: 'onAnyControllerBar'\r
         *                  }\r
         *              },\r
         *              store: {\r
         *                  '#baz': {\r
         *                      baz: 'onStoreBaz'\r
         *                  }\r
         *              }\r
         *          }\r
         *      });\r
         *\r
         * To listen to "idle" events fired by {@link Ext.GlobalEvents} when other event\r
         * processing is complete and Ext JS is about to return control to the browser:\r
         *\r
         *      Ext.define('AM.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          listen: {\r
         *              global: {            // Global events are always fired\r
         *                  idle: 'onIdle'   // from the same object, so there\r
         *              }                    // are no selectors\r
         *          }\r
         *      });\r
         *\r
         * As this relates to components, the following example:\r
         *\r
         *      Ext.define('AM.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          listen: {\r
         *              component: {\r
         *                  'useredit button[action=save]': {\r
         *                      click: 'updateUser'\r
         *                  }\r
         *              }\r
         *          }\r
         *      });\r
         *\r
         * Is equivalent to:\r
         *\r
         *      Ext.define('AM.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          control: {\r
         *              'useredit button[action=save]': {\r
         *                  click: 'updateUser'\r
         *              }\r
         *          }\r
         *      });\r
         *\r
         * Of course, these can all be combined in a single call and used instead of\r
         * `control`, like so:\r
         *\r
         *      Ext.define('AM.controller.Users', {\r
         *          extend: 'Ext.app.Controller',\r
         *\r
         *          listen: {\r
         *              global: {\r
         *                  idle: 'onIdle'\r
         *              },\r
         *              controller: {\r
         *                  '*': {\r
         *                      foobar: 'onAnyFooBar'\r
         *                  },\r
         *                  '#foo': {\r
         *                      bar: 'onFooBar'\r
         *                  }\r
         *              },\r
         *              component: {\r
         *                  'useredit button[action=save]': {\r
         *                      click: 'updateUser'\r
         *                  }\r
         *              },\r
         *              store: {\r
         *                  '#qux': {\r
         *                      load: 'onQuxLoad'\r
         *                  }\r
         *              }\r
         *          }\r
         *      });\r
         */\r
        listen: null,\r
\r
        /**\r
         * @cfg {Object} routes\r
         * @accessor\r
         *\r
         * An object of routes to handle hash changes. A route can be defined in a simple way:\r
         *\r
         *     routes : {\r
         *         'foo/bar'  : 'handleFoo',\r
         *         'user/:id' : 'showUser'\r
         *     }\r
         *\r
         * Where the property is the hash (which can accept a parameter defined by a colon) and the value\r
         * is the method on the controller to execute. The parameters will get sent in the action method.\r
         *\r
         * At the application level, you can define a event that will be executed when no matching\r
         * routes are found.\r
         *\r
         *     Ext.application({\r
         *         name: 'MyApp',\r
         *         listen: {\r
         *             controller: {\r
         *                 '#': {\r
         *                     unmatchedroute: 'onUnmatchedRoute'\r
         *                 }\r
         *             }\r
         *         },\r
         *\r
         *         onUnmatchedRoute: function(hash) {\r
         *             console.log('Unmatched', hash);\r
         *             // Do something...\r
         *         }\r
         *     });\r
         *\r
         * There is also a complex means of defining a route where you can use a before action and even\r
         * specify your own RegEx for the parameter:\r
         *\r
         *     routes : {\r
         *         'foo/bar'  : {\r
         *             action  : 'handleFoo',\r
         *             before  : 'beforeHandleFoo'\r
         *         },\r
         *         'user/:id' : {\r
         *             action     : 'showUser',\r
         *             before     : 'beforeShowUser',\r
         *             conditions : {\r
         *                 ':id' : '([0-9]+)'\r
         *             }\r
         *         }\r
         *     }\r
         *\r
         * This will only match if the `id` parameter is a number.\r
         *\r
         * The before action allows you to cancel an action. Every before action will get passed an `action` argument with\r
         * a `resume` and `stop` methods as the last argument of the method and you *MUST* execute either method:\r
         *\r
         *     beforeHandleFoo : function(action) {\r
         *         //some logic here\r
         *\r
         *         //this will allow the handleFoo action to be executed\r
         *         action.resume();\r
         *     },\r
         *     handleFoo : function() {\r
         *         //will get executed due to true being passed in callback in beforeHandleFoo\r
         *     },\r
         *     beforeShowUser : function(id, action) {\r
         *         //allows for async process like an Ajax\r
         *         Ext.Ajax.request({\r
         *             url     : 'foo.php',\r
         *             success : function() {\r
         *                 //will not allow the showUser method to be executed but will continue other queued actions.\r
         *                 action.stop();\r
         *             },\r
         *             failure : function() {\r
         *                 //will not allow the showUser method to be executed and will not allow other queued actions to be executed.\r
         *                 action.stop(true);\r
         *             }\r
         *         });\r
         *     },\r
         *     showUser : function(id) {\r
         *         //will not get executed due to false being passed in callback in beforeShowUser\r
         *     }\r
         *\r
         * You *MUST* execute the `resume` or `stop` method on the `action` argument. Executing `action.resume();` will continue\r
         * the action, `action.stop();` will not allow the action to resume but will allow other queued actions to resume,\r
         * `action.stop(true);` will not allow the action and any other queued actions to resume.\r
         *\r
         * The default RegEx that will be used is `([%a-zA-Z0-9\\-\\_\\s,]+)` but you can specify any\r
         * that may suit what you need to accomplish. An example of an advanced condition may be to make\r
         * a parameter optional and case-insensitive:\r
         *\r
         *     routes : {\r
         *         'user:id' : {\r
         *             action     : 'showUser',\r
         *             before     : 'beforeShowUser',\r
         *             conditions : {\r
         *                 ':id' : '(?:(?:\/){1}([%a-z0-9_,\s\-]+))?'\r
         *             }\r
         *         }\r
         *     }\r
         */\r
        routes : null,\r
        before : null\r
    },\r
\r
    /**\r
     * Creates new Controller.\r
     *\r
     * @param {Object} [config] Configuration object.\r
     */\r
    constructor: function(config) {\r
        var me = this;\r
\r
        // In versions prior to 5.1, this constructor used to call the Ext.util.Observable\r
        // constructor (which applied the config properties directly to the instance)\r
        // AND it used to call initConfig as well.  Since the constructor of\r
        // Ext.mixin.Observable calls initConfig, but does not apply the properties to\r
        // the instance, we do that here for backward compatibility.\r
        Ext.apply(me, config);\r
        // The control and listen properties are also methods so we need to delete them\r
        // from the instance after applying the config object.\r
        delete me.control;\r
        delete me.listen;\r
\r
        me.eventbus = Ext.app.EventBus;\r
\r
        //need to have eventbus property set before we initialize the config\r
        me.mixins.observable.constructor.call(me, config);\r
        // Assuming we haven't set this in updateControl or updateListen, force it here\r
        me.ensureId();\r
    },\r
\r
    applyListen: function(listen) {\r
        if (Ext.isObject(listen)) {\r
            listen = Ext.clone(listen);\r
        }\r
\r
        return listen;\r
    },\r
\r
    applyControl: function(control) {\r
        if (Ext.isObject(control)) {\r
            control = Ext.clone(control);\r
        }\r
\r
        return control;\r
    },\r
\r
    /**\r
     * @param {Object} control The object to pass to the {@link #method-control} method\r
     * @private\r
     */\r
    updateControl: function(control) {\r
        this.ensureId();\r
        if (control) {\r
            this.control(control);\r
        }\r
    },\r
\r
    /**\r
     * @param {Object} listen The object to pass to the {@link #method-listen} method\r
     * @private\r
     */\r
    updateListen: function(listen) {\r
        this.ensureId();\r
        if (listen) {\r
            this.listen(listen);\r
        }\r
    },\r
\r
    /**\r
     * @param {Object} routes The routes to connect to the {@link Ext.app.route.Router}\r
     * @private\r
     */\r
    updateRoutes : function(routes) {\r
        if (routes) {\r
            var me = this,\r
                befores = me.getBefore() || {},\r
                Router = Ext.app.route.Router,\r
                url, config, method;\r
\r
            for (url in routes) {\r
                config = routes[url];\r
\r
                if (Ext.isString(config)) {\r
                    config = {\r
                        action : config\r
                    };\r
                }\r
\r
                method = config.action;\r
\r
                if (!config.before) {\r
                    config.before = befores[method];\r
                }\r
                //<debug>\r
                else if (befores[method]) {\r
                    Ext.log.warn('You have a before method configured on a route ("' + url + '") and in the before object property also in the "' +\r
                        me.self.getName() + '" controller. Will use the before method in the route and disregard the one in the before property.');\r
                }\r
                //</debug>\r
\r
                //connect the route config to the Router\r
                Router.connect(url, config, me);\r
            }\r
        }\r
    },\r
\r
    isActive: function() {\r
        return true;\r
    },\r
\r
    /**\r
     * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an\r
     * object containing component paths mapped to a hash of listener functions.\r
     *\r
     * In the following example the `updateUser` function is mapped to to the `click`\r
     * event on a button component, which is a child of the `useredit` component.\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.control({\r
     *                  'useredit button[action=save]': {\r
     *                      click: this.updateUser\r
     *                  }\r
     *              });\r
     *          },\r
     *          \r
     *          updateUser: function(button) {\r
     *              console.log('clicked the Save button');\r
     *          }\r
     *      });\r
     *\r
     * Or alternatively one call `control` with two arguments:\r
     *\r
     *      this.control('useredit button[action=save]', {\r
     *          click: this.updateUser\r
     *      });\r
     *\r
     * See {@link Ext.ComponentQuery} for more information on component selectors.\r
     *\r
     * @param {String/Object} selectors If a String, the second argument is used as the\r
     * listeners, otherwise an object of selectors -> listeners is assumed\r
     * @param {Object} [listeners] Config for listeners.\r
     */\r
    control: function(selectors, listeners, controller) {\r
        var me = this,\r
            ctrl = controller,\r
            obj;\r
\r
        if (Ext.isString(selectors)) {\r
            obj = {};\r
            obj[selectors] = listeners;\r
        }\r
        else {\r
            obj = selectors;\r
            ctrl = listeners;\r
        }\r
\r
        me.eventbus.control(obj, ctrl || me);\r
    },\r
\r
    /**\r
     * Adds listeners to different event sources (also called "event domains"). The\r
     * primary event domain is that of components, but there are also other event domains:\r
     * {@link Ext.app.domain.Global Global} domain that intercepts events fired from\r
     * {@link Ext.GlobalEvents} Observable instance, {@link Ext.app.domain.Controller Controller}\r
     * domain can be used to listen to events fired by other Controllers,\r
     * {@link Ext.app.domain.Store Store} domain gives access to Store events, and\r
     * {@link Ext.app.domain.Direct Direct} domain can be used with Ext Direct Providers\r
     * to listen to their events.\r
     * \r
     * To listen to "bar" events fired by a controller with id="foo":\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.listen({\r
     *                  controller: {\r
     *                      '#foo': {\r
     *                         bar: this.onFooBar\r
     *                      }\r
     *                  }\r
     *              });\r
     *          },\r
     *          ...\r
     *      });\r
     * \r
     * To listen to "bar" events fired by any controller, and "baz" events\r
     * fired by Store with storeId="baz":\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.listen({\r
     *                  controller: {\r
     *                      '*': {\r
     *                         bar: this.onAnyControllerBar\r
     *                      }\r
     *                  },\r
     *                  store: {\r
     *                      '#baz': {\r
     *                          baz: this.onStoreBaz\r
     *                      }\r
     *                  }\r
     *              });\r
     *          },\r
     *          ...\r
     *      });\r
     *\r
     * To listen to "idle" events fired by {@link Ext.GlobalEvents} when other event\r
     * processing is complete and Ext JS is about to return control to the browser:\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.listen({\r
     *                  global: {               // Global events are always fired\r
     *                      idle: this.onIdle   // from the same object, so there\r
     *                  }                       // are no selectors\r
     *              });\r
     *          }\r
     *      });\r
     * \r
     * As this relates to components, the following example:\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.listen({\r
     *                  component: {\r
     *                      'useredit button[action=save]': {\r
     *                         click: this.updateUser\r
     *                      }\r
     *                  }\r
     *              });\r
     *          },\r
     *          ...\r
     *      });\r
     * \r
     * Is equivalent to:\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.control({\r
     *                  'useredit button[action=save]': {\r
     *                     click: this.updateUser\r
     *                  }\r
     *              });\r
     *          },\r
     *          ...\r
     *      });\r
     *\r
     * Of course, these can all be combined in a single call and used instead of\r
     * `control`, like so:\r
     *\r
     *      Ext.define('AM.controller.Users', {\r
     *          init: function() {\r
     *              this.listen({\r
     *                  global: {\r
     *                      idle: this.onIdle\r
     *                  },\r
     *                  controller: {\r
     *                      '*': {\r
     *                         foobar: this.onAnyFooBar\r
     *                      },\r
     *                      '#foo': {\r
     *                         bar: this.onFooBar\r
     *                      }\r
     *                  },\r
     *                  component: {\r
     *                      'useredit button[action=save]': {\r
     *                         click: this.updateUser\r
     *                      }\r
     *                  },\r
     *                  store: {\r
     *                      '#qux': {\r
     *                          load: this.onQuxLoad\r
     *                      }\r
     *                  }\r
     *              });\r
     *          },\r
     *          ...\r
     *      });\r
     *\r
     * @param {Object} to Config object containing domains, selectors and listeners.\r
     * @param {Ext.app.Controller} [controller] The controller to add the listeners to. Defaults to the current controller.\r
     */\r
    listen: function (to, controller) {\r
        this.eventbus.listen(to, controller || this);\r
    },\r
    \r
    destroy: function() {\r
        var me = this,\r
            bus = me.eventbus;\r
\r
        Ext.app.route.Router.disconnectAll(me);\r
\r
        if (bus) {\r
            bus.unlisten(me);\r
            me.eventbus = null;\r
        }\r
        me.callParent();\r
    },\r
\r
    /**\r
     * Update the hash. By default, it will not execute the routes if the current token and the\r
     * token passed are the same.\r
     * \r
     * @param {String/Ext.data.Model} token The token to redirect to.  Can be either a String\r
     * or a {@link Ext.data.Model Model} instance - if a Model instance is passed it will\r
     * internally be converted into a String token by calling the Model's\r
     * {@link Ext.data.Model#toUrl toUrl} function.\r
     *\r
     * @param {Boolean} force Force the update of the hash regardless of the current token.\r
     * \r
     * @return {Boolean} Will return `true` if the token was updated.\r
     */\r
    redirectTo: function(token, force) {\r
        if (token.isModel) {\r
            token = token.toUrl();\r
        }\r
        if (!force) {\r
            var currentToken = Ext.util.History.getToken();\r
\r
            if (currentToken === token) {\r
                return false;\r
            }\r
        } else {\r
            Ext.app.route.Router.onStateChange(token);\r
        }\r
        Ext.util.History.add(token);\r
\r
        return true;\r
    }\r
});\r