add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / app / route / Router.js

/**\r
 * The Router is an ordered set of {@link Ext.app.route.Route} definitions that decode a\r
 * url into a controller function to execute. Each `route` defines a type of url to match,\r
 * along with the controller function to call if it is matched. The Router uses the\r
 * {@link Ext.util.History} singleton to find out when the browser's url has changed.\r
 *\r
 * Routes are almost always defined inside a {@link Ext.app.Controller Controller}, as\r
 * opposed to on the Router itself. End-developers should not usually need to interact\r
 * directly with the Router as the Controllers manage everything automatically. See the\r
 * {@link Ext.app.Controller Controller documentation} for more information on specifying\r
 * routes.\r
 *\r
 * @private\r
 */\r
Ext.define('Ext.app.route.Router', {\r
    singleton : true,\r
\r
    requires : [\r
        'Ext.app.route.Queue',\r
        'Ext.app.route.Route',\r
        'Ext.util.History'\r
    ],\r
\r
    /**\r
     * @property {String} [multipleToken=|] The token to split the routes to support multiple routes.\r
     */\r
    multipleToken: '|',\r
\r
    /**\r
     * @property {Boolean} queueRoutes True to queue routes to be executed one after the\r
     * other, false to execute routes immediately.\r
     */\r
    queueRoutes: true,\r
\r
    /**\r
     * @property {Ext.app.route.Route[]} routes The connected {@link Ext.app.route.Route}\r
     * instances.\r
     */\r
\r
    constructor : function () {\r
        var History = Ext.util.History;\r
\r
        if (!History.ready) {\r
            History.init();\r
        }\r
\r
        History.on('change', this.onStateChange, this);\r
        this.clear();\r
    },\r
\r
    /**\r
     * React to a token\r
     *\r
     * @private\r
     * @param {String} token The token to react to.\r
     */\r
    onStateChange : function (token) {\r
        var me          = this,\r
            app         = me.application,\r
            routes      = me.routes,\r
            len         = routes.length,\r
            queueRoutes = me.queueRoutes,\r
            tokens      = token.split(me.multipleToken),\r
            t           = 0,\r
            length      = tokens.length,\r
            i, queue, route, args, matched;\r
\r
        for (; t < length; t++) {\r
            token = tokens[t];\r
            matched = false;\r
\r
            if (queueRoutes) {\r
                //create a queue\r
                queue = new Ext.app.route.Queue({\r
                    token : token\r
                });\r
            }\r
\r
            for (i = 0; i < len; i++) {\r
                route = routes[i];\r
                args  = route.recognize(token);\r
\r
                if (args) {\r
                    matched = true;\r
                    if (queueRoutes) {\r
                        queue.queueAction(route, args);\r
                    } else {\r
                        route.execute(token, args);\r
                    }\r
                }\r
            }\r
\r
            if (queueRoutes) {\r
                //run the queue\r
                queue.runQueue();\r
            }\r
            \r
            if (!matched && app) {\r
                app.fireEvent('unmatchedroute', token);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Create the {@link Ext.app.route.Route} instance and connect to the\r
     * {@link Ext.app.route.Router} singleton.\r
     *\r
     * @param {String} url The url to recognize.\r
     * @param {String} action The action on the controller to execute when the url is\r
     * matched.\r
     * @param {Ext.app.Controller} controller The controller associated with the\r
     * {@link Ext.app.route.Route}\r
     */\r
    connect : function (url, action, controller) {\r
        var config = {\r
                url        : url,\r
                action     : action,\r
                controller : controller\r
            };\r
\r
        if (Ext.isObject(action)) {\r
            Ext.merge(config, action);\r
        }\r
        this.routes.push(new Ext.app.route.Route(config));\r
    },\r
    \r
    /**\r
     * Disconnects all routes for a controller.\r
     * @param {Ext.app.Controller} controller The controller to disconnect routes from.\r
     */\r
    disconnectAll: function(controller) {\r
        var routes = this.routes,\r
            len = routes.length,\r
            newRoutes = [],\r
            i, route;\r
    \r
        for (i = 0; i < len; ++i) {\r
            route = routes[i];\r
            if (route.controller !== controller) {\r
                newRoutes.push(route);\r
            }\r
        }\r
        this.routes = newRoutes;\r
    },\r
\r
    /**\r
     * Recognizes a url string connected to the Router, return the controller/action pair\r
     * plus any additional config associated with it.\r
     *\r
     * @param {String} url The url to recognize.\r
     * @return {Object/Boolean} If the url was recognized, the controller and action to\r
     * call, else `false`.\r
     */\r
    recognize : function(url) {\r
        var routes = this.routes || [],\r
            i      = 0,\r
            len    = routes.length,\r
            route, args;\r
\r
        for (; i < len; i++) {\r
            route = routes[i];\r
            args  = route.recognize(url);\r
\r
            if (args) {\r
                //route is recognized, return it and the arguments recognized if any\r
                return {\r
                    route : route,\r
                    args  : args\r
                };\r
            }\r
        }\r
\r
        return false;\r
    },\r
\r
    /**\r
     * Convenience method which just calls the supplied function with the\r
     * {@link Ext.app.route.Router} singleton. Example usage:\r
     *\r
     *     Ext.app.route.Router.draw(function(map) {\r
     *         map.connect('activate/:token', {controller: 'users', action: 'activate'});\r
     *         map.connect('home',            {controller: 'index', action: 'home'});\r
     *     });\r
     *\r
     * @param {Function} fn The function to call\r
     */\r
    draw : function(fn) {\r
        fn.call(this, this);\r
    },\r
\r
    /**\r
     * Clear all the recognized routes.\r
     */\r
    clear : function() {\r
        this.routes = [];\r
    }\r
});\r