add extjs 6.0.1 sources

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

/**\r
 * Represents a mapping between a url and a controller/action pair. May also contain\r
 * additional params.\r
 *\r
 * This is a private internal class that should not need to be used by end-developer code.\r
 * Its API and existence are subject to change so use at your own risk.\r
 *\r
 * @private\r
 */\r
Ext.define('Ext.app.route.Route', {\r
    /**\r
     * @cfg {String} action The name of the action that will be called on the\r
     * {@link #controller} if this route is matched.\r
     */\r
    action: null,\r
\r
    /**\r
     * @cfg {Object} conditions Optional set of conditions for each token in the url\r
     * string. Each key should be one of the tokens, each value should be a regex that the\r
     * token should accept. For example, if you have a Route with a url like\r
     * `"files/:fileName"` and you want it to match urls like "files/someImage.jpg" then\r
     * you can set these conditions to allow the :fileName token to accept strings\r
     * containing a period ("."):\r
     *\r
     *     conditions: {\r
     *         ':fileName': "[0-9a-zA-Z\.]+"\r
     *     }\r
     */\r
    conditions: null,\r
\r
    /**\r
     * @cfg {String} controller The name of the Controller whose {@link #action} will be\r
     * called if this route is matched.\r
     */\r
    controller: null,\r
    \r
    /**\r
     * @cfg {Boolean} allowInactive `true` to allow this route to be triggered on\r
     * a controller that is not active.\r
     */\r
    allowInactive: false,\r
\r
    /**\r
     * @cfg {String} url (required) The url regex to match against.\r
     */\r
    url: null,\r
\r
    /**\r
     * @cfg {Function} before An optional function used to intercept {@link #action}\r
     * to do perform additional tasks and possibly stop the execution. An example is if the route is\r
     * for editing a user and you need to verify the current user has permission. You could\r
     * send an {@link Ext.Ajax} request to a server or some arbitrary code.\r
     *\r
     * This function MUST be executed by passing in a Boolean\r
     * value to allow execution of the configured action on {@link Ext.app.route.Route}.\r
     *\r
     * Defaults to `null`\r
     */\r
    before: null,\r
\r
    /**\r
     * @cfg {Boolean} caseInsensitive `true` to allow the tokens to be matched with\r
     * case-insensitive. Defaults to `false` which will force case matching.\r
     */\r
    caseInsensitive: false,\r
\r
    /**\r
     * A regular expression to match the token to the configured {@link #url}.\r
     *\r
     * @private\r
     */\r
    matcherRegex: null,\r
\r
    /**\r
     * A regular expression to check if there are parameters in the configured {@link #url}.\r
     *\r
     * @private\r
     */\r
    paramMatchingRegex: null,\r
\r
    /**\r
     * An array of parameters in the configured {@link #url}.\r
     *\r
     * @private\r
     */\r
    paramsInMatchString: null,\r
\r
    constructor : function(config) {\r
        var me = this,\r
            url;\r
\r
        Ext.apply(me, config, {\r
            conditions : {}\r
        });\r
\r
        url = me.url;\r
\r
        me.paramMatchingRegex  = new RegExp(/:([0-9A-Za-z\_]*)/g);\r
        me.paramsInMatchString = url.match(me.paramMatchingRegex) || [];\r
        me.matcherRegex        = me.createMatcherRegex(url);\r
    },\r
\r
    /**\r
     * Attempts to recognize a given url string and return controller/action pair for it.\r
     *\r
     * @param {String} url The url to recognize.\r
     * @return {Object/Boolean} The matched data, or `false` if no match.\r
     */\r
    recognize : function(url) {\r
        var me = this,\r
            controller = me.controller,\r
            matches, args;\r
\r
        if ((me.allowInactive || controller.isActive()) && me.recognizes(url)) {\r
            //find parameter matches\r
            matches = me.matchesFor(url);\r
            //find the arguments for the parameters\r
            args    = url.match(me.matcherRegex);\r
\r
            //first one is the entire match, remove\r
            args.shift();\r
\r
            return Ext.applyIf(matches, {\r
                controller : controller,\r
                action     : me.action,\r
                historyUrl : url,\r
                args       : args\r
            });\r
        }\r
\r
        return false;\r
    },\r
\r
    /**\r
     * Returns true if this {@link Ext.app.route.Route} matches the given url string.\r
     *\r
     * @private\r
     * @param {String} url The url to test.\r
     * @return {Boolean} `true` if this {@link Ext.app.route.Route} recognizes the url.\r
     */\r
    recognizes : function (url) {\r
        return this.matcherRegex.test(url);\r
    },\r
\r
    /**\r
     * The method to execute the action using the configured before function which will\r
     * kick off the actual {@link #action} on the {@link #controller}.\r
     *\r
     * @private\r
     * @param {String} token The hash to execute with.\r
     * @param {Object} argConfig The object from the {@link Ext.app.route.Route}'s\r
     * recognize method call.\r
     * @param {Function} callback An optional callback function to execute after the\r
     * {@link #action} is executed.\r
     * @param {Object} scope The scope to execute the callback with, defaults to this\r
     * {@link Ext.app.route.Route}.\r
     */\r
    execute : function(token, argConfig, callback, scope) {\r
        var args           = argConfig.args || [],\r
            before         = this.before,\r
            controller     = this.controller,\r
            beforeCallback = this.createCallback(argConfig, callback, scope);\r
\r
        if (before) {\r
            args.push(beforeCallback);\r
\r
            if (Ext.isString(before)) {\r
                //get method from the controller\r
                before = this.before = controller[before];\r
            }\r
\r
            if (before) {\r
                before.apply(controller, args);\r
            }\r
            //<debug>\r
            else {\r
                Ext.log.warn('The before action: ' + this.before +\r
                    ' was not found on the controller. The action method will not be executed.');\r
            }\r
            //</debug>\r
        } else {\r
            //If no before was specified, proceed to action\r
            beforeCallback.resume();\r
        }\r
    },\r
\r
    /**\r
     * Returns a hash of matching url segments for the given url.\r
     *\r
     * @private\r
     * @param {String} url The url to extract matches for\r
     * @return {Object} matching url segments\r
     */\r
    matchesFor : function (url) {\r
        var params = {},\r
            keys   = this.paramsInMatchString,\r
            values = url.match(this.matcherRegex),\r
            i      = 0,\r
            len    = keys.length;\r
\r
        //first value is the entire match so reject\r
        values.shift();\r
\r
        for (; i < len; i++) {\r
            params[keys[i].replace(':', '')] = values[i];\r
        }\r
\r
        return params;\r
    },\r
\r
    /**\r
     * Takes the configured url string including wildcards and returns a regex that can be\r
     * used to match against a url.\r
     *\r
     * @private\r
     * @param {String} url The url string.\r
     * @return {RegExp} The matcher regex.\r
     */\r
    createMatcherRegex : function (url) {\r
        // Converts a route string into an array of symbols starting with a colon. e.g.\r
        // ":controller/:action/:id" => [':controller', ':action', ':id']\r
        //\r
        var paramsInMatchString = this.paramsInMatchString,\r
            conditions          = this.conditions,\r
            i                   = 0,\r
            len                 = paramsInMatchString.length,\r
            format              = Ext.util.Format.format,\r
            modifiers           = this.caseInsensitive ? 'i' : '',\r
            params, cond, matcher;\r
\r
        for (; i < len; i++) {\r
            params  = paramsInMatchString[i];\r
            cond    = conditions[params];\r
            matcher = format('{0}', cond || '([%a-zA-Z0-9\\-\\_\\s,]+)');\r
\r
            url = url.replace(new RegExp(params), matcher);\r
        }\r
\r
        //we want to match the whole string, so include the anchors\r
        return new RegExp('^' + url + '$', modifiers);\r
    },\r
\r
    /**\r
     * Creates the callback function to execute in the configured {@link #before} function.\r
     *\r
     * @private\r
     * @param {Object} args The arguments found from the {@link Ext.app.route.Route}'s\r
     * recognize call.\r
     * @param {Function} callback The function to be executed after the {@link #action}\r
     * has been executed.\r
     * @param {Object} scope The scope to execute on the callback function, defaults to\r
     * the {@link Ext.app.route.Route}.\r
     * @return {Object} An object with the `resume` and `stop` methods on it to control to continue\r
     * with the action or not.\r
     */\r
    createCallback : function (args, callback, scope) {\r
        var me = this;\r
\r
        scope = scope || me;\r
\r
        return {\r
            resume : function() {\r
                var controller = me.controller,\r
                    action = me.action,\r
                    resume;\r
\r
                if (Ext.isString(action)) {\r
                    //get method from the controller\r
                    action = controller[action];\r
                }\r
\r
                //get the parameter arguments\r
                args = args && args.args ? args.args : [];\r
\r
                //remove the action argument from the before method\r
                resume = args.pop();\r
\r
                if (resume && !Ext.isObject(resume)) {\r
                    args.push(resume);\r
                }\r
\r
                //make sure there is an action\r
                if (action) {\r
                    me.action = action;\r
\r
                    //execute the action on the controller scoping to the controller\r
                    action.apply(controller, args);\r
                }\r
                //<debug>\r
                else {\r
                    Ext.log.warn('The action: ' + me.action + ' was not found on the controller.');\r
                }\r
                //</debug>\r
\r
                if (callback) {\r
                    callback.call(scope);\r
                }\r
            },\r
\r
            stop : function(all) {\r
                if (callback) {\r
                    callback.call(scope, all);\r
                }\r
            }\r
        };\r
    }\r
});\r