1 YUI.add('router', function (Y, NAME) {

     2 

     3 /**

     4 Provides URL-based routing using HTML5 `pushState()` or the location hash.

     5 

     6 @module app

     7 @submodule router

     8 @since 3.4.0

     9 **/

    10 

    11 var HistoryHash = Y.HistoryHash,

    12     QS          = Y.QueryString,

    13     YArray      = Y.Array,

    14     YLang       = Y.Lang,

    15     YObject     = Y.Object,

    16 

    17     win = Y.config.win,

    18 

    19     // Holds all the active router instances. This supports the static

    20     // `dispatch()` method which causes all routers to dispatch.

    21     instances = [],

    22 

    23     // We have to queue up pushState calls to avoid race conditions, since the

    24     // popstate event doesn't actually provide any info on what URL it's

    25     // associated with.

    26     saveQueue = [],

    27 

    28     /**

    29     Fired when the router is ready to begin dispatching to route handlers.

    30 

    31     You shouldn't need to wait for this event unless you plan to implement some

    32     kind of custom dispatching logic. It's used internally in order to avoid

    33     dispatching to an initial route if a browser history change occurs first.

    34 

    35     @event ready

    36     @param {Boolean} dispatched `true` if routes have already been dispatched

    37       (most likely due to a history change).

    38     @fireOnce

    39     **/

    40     EVT_READY = 'ready';

    41 

    42 /**

    43 Provides URL-based routing using HTML5 `pushState()` or the location hash.

    44 

    45 This makes it easy to wire up route handlers for different application states

    46 while providing full back/forward navigation support and bookmarkable, shareable

    47 URLs.

    48 

    49 @class Router

    50 @param {Object} [config] Config properties.

    51     @param {Boolean} [config.html5] Overrides the default capability detection

    52         and forces this router to use (`true`) or not use (`false`) HTML5

    53         history.

    54     @param {String} [config.root=''] Root path from which all routes should be

    55         evaluated.

    56     @param {Array} [config.routes=[]] Array of route definition objects.

    57 @constructor

    58 @extends Base

    59 @since 3.4.0

    60 **/

    61 function Router() {

    62     Router.superclass.constructor.apply(this, arguments);

    63 }

    64 

    65 Y.Router = Y.extend(Router, Y.Base, {

    66     // -- Protected Properties -------------------------------------------------

    67 

    68     /**

    69     Whether or not `_dispatch()` has been called since this router was

    70     instantiated.

    71 

    72     @property _dispatched

    73     @type Boolean

    74     @default undefined

    75     @protected

    76     **/

    77 

    78     /**

    79     Whether or not we're currently in the process of dispatching to routes.

    80 

    81     @property _dispatching

    82     @type Boolean

    83     @default undefined

    84     @protected

    85     **/

    86 

    87     /**

    88     History event handle for the `history:change` or `hashchange` event

    89     subscription.

    90 

    91     @property _historyEvents

    92     @type EventHandle

    93     @protected

    94     **/

    95 

    96     /**

    97     Cached copy of the `html5` attribute for internal use.

    98 

    99     @property _html5

   100     @type Boolean

   101     @protected

   102     **/

   103 

   104     /**

   105     Map which holds the registered param handlers in the form:

   106     `name` -> RegExp | Function.

   107 

   108     @property _params

   109     @type Object

   110     @protected

   111     @since 3.12.0

   112     **/

   113 

   114     /**

   115     Whether or not the `ready` event has fired yet.

   116 

   117     @property _ready

   118     @type Boolean

   119     @default undefined

   120     @protected

   121     **/

   122 

   123     /**

   124     Regex used to break up a URL string around the URL's path.

   125 

   126     Subpattern captures:

   127 

   128       1. Origin, everything before the URL's path-part.

   129       2. The URL's path-part.

   130       3. The URL's query.

   131       4. The URL's hash fragment.

   132 

   133     @property _regexURL

   134     @type RegExp

   135     @protected

   136     @since 3.5.0

   137     **/

   138     _regexURL: /^((?:[^\/#?:]+:\/\/|\/\/)[^\/]*)?([^?#]*)(\?[^#]*)?(#.*)?$/,

   139 

   140     /**

   141     Regex used to match parameter placeholders in route paths.

   142 

   143     Subpattern captures:

   144 

   145       1. Parameter prefix character. Either a `:` for subpath parameters that

   146          should only match a single level of a path, or `*` for splat parameters

   147          that should match any number of path levels.

   148 

   149       2. Parameter name, if specified, otherwise it is a wildcard match.

   150 

   151     @property _regexPathParam

   152     @type RegExp

   153     @protected

   154     **/

   155     _regexPathParam: /([:*])([\w\-]+)?/g,

   156 

   157     /**

   158     Regex that matches and captures the query portion of a URL, minus the

   159     preceding `?` character, and discarding the hash portion of the URL if any.

   160 

   161     @property _regexUrlQuery

   162     @type RegExp

   163     @protected

   164     **/

   165     _regexUrlQuery: /\?([^#]*).*$/,

   166 

   167     /**

   168     Regex that matches everything before the path portion of a URL (the origin).

   169     This will be used to strip this part of the URL from a string when we

   170     only want the path.

   171 

   172     @property _regexUrlOrigin

   173     @type RegExp

   174     @protected

   175     **/

   176     _regexUrlOrigin: /^(?:[^\/#?:]+:\/\/|\/\/)[^\/]*/,

   177 

   178     /**

   179     Collection of registered routes.

   180 

   181     @property _routes

   182     @type Array

   183     @protected

   184     **/

   185 

   186     // -- Lifecycle Methods ----------------------------------------------------

   187     initializer: function (config) {

   188         var self = this;

   189 

   190         self._html5  = self.get('html5');

   191         self._params = {};

   192         self._routes = [];

   193         self._url    = self._getURL();

   194 

   195         // Necessary because setters don't run on init.

   196         self._setRoutes(config && config.routes ? config.routes :

   197                 self.get('routes'));

   198 

   199         // Set up a history instance or hashchange listener.

   200         if (self._html5) {

   201             self._history       = new Y.HistoryHTML5({force: true});

   202             self._historyEvents =

   203                     Y.after('history:change', self._afterHistoryChange, self);

   204         } else {

   205             self._historyEvents =

   206                     Y.on('hashchange', self._afterHistoryChange, win, self);

   207         }

   208 

   209         // Fire a `ready` event once we're ready to route. We wait first for all

   210         // subclass initializers to finish, then for window.onload, and then an

   211         // additional 20ms to allow the browser to fire a useless initial

   212         // `popstate` event if it wants to (and Chrome always wants to).

   213         self.publish(EVT_READY, {

   214             defaultFn  : self._defReadyFn,

   215             fireOnce   : true,

   216             preventable: false

   217         });

   218 

   219         self.once('initializedChange', function () {

   220             Y.once('load', function () {

   221                 setTimeout(function () {

   222                     self.fire(EVT_READY, {dispatched: !!self._dispatched});

   223                 }, 20);

   224             });

   225         });

   226 

   227         // Store this router in the collection of all active router instances.

   228         instances.push(this);

   229     },

   230 

   231     destructor: function () {

   232         var instanceIndex = YArray.indexOf(instances, this);

   233 

   234         // Remove this router from the collection of active router instances.

   235         if (instanceIndex > -1) {

   236             instances.splice(instanceIndex, 1);

   237         }

   238 

   239         if (this._historyEvents) {

   240             this._historyEvents.detach();

   241         }

   242     },

   243 

   244     // -- Public Methods -------------------------------------------------------

   245 

   246     /**

   247     Dispatches to the first route handler that matches the current URL, if any.

   248 

   249     If `dispatch()` is called before the `ready` event has fired, it will

   250     automatically wait for the `ready` event before dispatching. Otherwise it

   251     will dispatch immediately.

   252 

   253     @method dispatch

   254     @chainable

   255     **/

   256     dispatch: function () {

   257         this.once(EVT_READY, function () {

   258             var req, res;

   259 

   260             this._ready = true;

   261 

   262             if (!this.upgrade()) {

   263                 req = this._getRequest('dispatch');

   264                 res = this._getResponse(req);

   265 

   266                 this._dispatch(req, res);

   267             }

   268         });

   269 

   270         return this;

   271     },

   272 

   273     /**

   274     Gets the current route path.

   275 

   276     @method getPath

   277     @return {String} Current route path.

   278     **/

   279     getPath: function () {

   280         return this._getPath();

   281     },

   282 

   283     /**

   284     Returns `true` if this router has at least one route that matches the

   285     specified URL, `false` otherwise.

   286 

   287     This method enforces the same-origin security constraint on the specified

   288     `url`; any URL which is not from the same origin as the current URL will

   289     always return `false`.

   290 

   291     @method hasRoute

   292     @param {String} url URL to match.

   293     @return {Boolean} `true` if there's at least one matching route, `false`

   294       otherwise.

   295     **/

   296     hasRoute: function (url) {

   297         var path;

   298 

   299         if (!this._hasSameOrigin(url)) {

   300             return false;

   301         }

   302 

   303         if (!this._html5) {

   304             url = this._upgradeURL(url);

   305         }

   306 

   307         // Get just the path portion of the specified `url`.

   308         path = this.removeQuery(url.replace(this._regexUrlOrigin, ''));

   309 

   310         return !!this.match(path).length;

   311     },

   312 

   313     /**

   314     Returns an array of route objects that match the specified URL path.

   315 

   316     If this router has a `root`, then the specified `path` _must_ be

   317     semantically within the `root` path to match any routes.

   318 

   319     This method is called internally to determine which routes match the current

   320     path whenever the URL changes. You may override it if you want to customize

   321     the route matching logic, although this usually shouldn't be necessary.

   322 

   323     Each returned route object has the following properties:

   324 

   325       * `callback`: A function or a string representing the name of a function

   326         this router that should be executed when the route is triggered.

   327 

   328       * `keys`: An array of strings representing the named parameters defined in

   329         the route's path specification, if any.

   330 

   331       * `path`: The route's path specification, which may be either a string or

   332         a regex.

   333 

   334       * `regex`: A regular expression version of the route's path specification.

   335         This regex is used to determine whether the route matches a given path.

   336 

   337     @example

   338         router.route('/foo', function () {});

   339         router.match('/foo');

   340         // => [{callback: ..., keys: [], path: '/foo', regex: ...}]

   341 

   342     @method match

   343     @param {String} path URL path to match. This should be an absolute path that

   344         starts with a slash: "/".

   345     @return {Object[]} Array of route objects that match the specified path.

   346     **/

   347     match: function (path) {

   348         var root = this.get('root');

   349 

   350         if (root) {

   351             // The `path` must be semantically within this router's `root` path

   352             // or mount point, if it's not then no routes should be considered a

   353             // match.

   354             if (!this._pathHasRoot(root, path)) {

   355                 return [];

   356             }

   357 

   358             // Remove this router's `root` from the `path` before checking the

   359             // routes for any matches.

   360             path = this.removeRoot(path);

   361         }

   362 

   363         return YArray.filter(this._routes, function (route) {

   364             return path.search(route.regex) > -1;

   365         });

   366     },

   367 

   368     /**

   369     Adds a handler for a route param specified by _name_.

   370 

   371     Param handlers can be registered via this method and are used to

   372     validate/format values of named params in routes before dispatching to the

   373     route's handler functions. Using param handlers allows routes to defined

   374     using string paths which allows for `req.params` to use named params, but

   375     still applying extra validation or formatting to the param values parsed

   376     from the URL.

   377 

   378     If a param handler regex or function returns a value of `false`, `null`,

   379     `undefined`, or `NaN`, the current route will not match and be skipped. All

   380     other return values will be used in place of the original param value parsed

   381     from the URL.

   382 

   383     @example

   384         router.param('postId', function (value) {

   385             return parseInt(value, 10);

   386         });

   387 

   388         router.param('username', /^\w+$/);

   389 

   390         router.route('/posts/:postId', function (req) {

   391             Y.log('Post: ' + req.params.id);

   392         });

   393 

   394         router.route('/users/:username', function (req) {

   395             // `req.params.username` is an array because the result of calling

   396             // `exec()` on the regex is assigned as the param's value.

   397             Y.log('User: ' + req.params.username[0]);

   398         });

   399 

   400         router.route('*', function () {

   401             Y.log('Catch-all no routes matched!');

   402         });

   403 

   404         // URLs which match routes:

   405         router.save('/posts/1');     // => "Post: 1"

   406         router.save('/users/ericf'); // => "User: ericf"

   407 

   408         // URLs which do not match routes because params fail validation:

   409         router.save('/posts/a');            // => "Catch-all no routes matched!"

   410         router.save('/users/ericf,rgrove'); // => "Catch-all no routes matched!"

   411 

   412     @method param

   413     @param {String} name Name of the param used in route paths.

   414     @param {Function|RegExp} handler Function to invoke or regular expression to

   415         `exec()` during route dispatching whose return value is used as the new

   416         param value. Values of `false`, `null`, `undefined`, or `NaN` will cause

   417         the current route to not match and be skipped. When a function is

   418         specified, it will be invoked in the context of this instance with the

   419         following parameters:

   420       @param {String} handler.value The current param value parsed from the URL.

   421       @param {String} handler.name The name of the param.

   422     @chainable

   423     @since 3.12.0

   424     **/

   425     param: function (name, handler) {

   426         this._params[name] = handler;

   427         return this;

   428     },

   429 

   430     /**

   431     Removes the `root` URL from the front of _url_ (if it's there) and returns

   432     the result. The returned path will always have a leading `/`.

   433 

   434     @method removeRoot

   435     @param {String} url URL.

   436     @return {String} Rootless path.

   437     **/

   438     removeRoot: function (url) {

   439         var root = this.get('root'),

   440             path;

   441 

   442         // Strip out the non-path part of the URL, if any (e.g.

   443         // "http://foo.com"), so that we're left with just the path.

   444         url = url.replace(this._regexUrlOrigin, '');

   445 

   446         // Return the host-less URL if there's no `root` path to further remove.

   447         if (!root) {

   448             return url;

   449         }

   450 

   451         path = this.removeQuery(url);

   452 

   453         // Remove the `root` from the `url` if it's the same or its path is

   454         // semantically within the root path.

   455         if (path === root || this._pathHasRoot(root, path)) {

   456             url = url.substring(root.length);

   457         }

   458 

   459         return url.charAt(0) === '/' ? url : '/' + url;

   460     },

   461 

   462     /**

   463     Removes a query string from the end of the _url_ (if one exists) and returns

   464     the result.

   465 

   466     @method removeQuery

   467     @param {String} url URL.

   468     @return {String} Queryless path.

   469     **/

   470     removeQuery: function (url) {

   471         return url.replace(/\?.*$/, '');

   472     },

   473 

   474     /**

   475     Replaces the current browser history entry with a new one, and dispatches to

   476     the first matching route handler, if any.

   477 

   478     Behind the scenes, this method uses HTML5 `pushState()` in browsers that

   479     support it (or the location hash in older browsers and IE) to change the

   480     URL.

   481 

   482     The specified URL must share the same origin (i.e., protocol, host, and

   483     port) as the current page, or an error will occur.

   484 

   485     @example

   486         // Starting URL: http://example.com/

   487 

   488         router.replace('/path/');

   489         // New URL: http://example.com/path/

   490 

   491         router.replace('/path?foo=bar');

   492         // New URL: http://example.com/path?foo=bar

   493 

   494         router.replace('/');

   495         // New URL: http://example.com/

   496 

   497     @method replace

   498     @param {String} [url] URL to set. This URL needs to be of the same origin as

   499       the current URL. This can be a URL relative to the router's `root`

   500       attribute. If no URL is specified, the page's current URL will be used.

   501     @chainable

   502     @see save()

   503     **/

   504     replace: function (url) {

   505         return this._queue(url, true);

   506     },

   507 

   508     /**

   509     Adds a route handler for the specified `route`.

   510 

   511     The `route` parameter may be a string or regular expression to represent a

   512     URL path, or a route object. If it's a string (which is most common), it may

   513     contain named parameters: `:param` will match any single part of a URL path

   514     (not including `/` characters), and `*param` will match any number of parts

   515     of a URL path (including `/` characters). These named parameters will be

   516     made available as keys on the `req.params` object that's passed to route

   517     handlers.

   518 

   519     If the `route` parameter is a regex, all pattern matches will be made

   520     available as numbered keys on `req.params`, starting with `0` for the full

   521     match, then `1` for the first subpattern match, and so on.

   522 

   523     Alternatively, an object can be provided to represent the route and it may

   524     contain a `path` property which is a string or regular expression which

   525     causes the route to be process as described above. If the route object

   526     already contains a `regex` or `regexp` property, the route will be

   527     considered fully-processed and will be associated with any `callacks`

   528     specified on the object and those specified as parameters to this method.

   529     **Note:** Any additional data contained on the route object will be

   530     preserved.

   531 

   532     Here's a set of sample routes along with URL paths that they match:

   533 

   534       * Route: `/photos/:tag/:page`

   535         * URL: `/photos/kittens/1`, params: `{tag: 'kittens', page: '1'}`

   536         * URL: `/photos/puppies/2`, params: `{tag: 'puppies', page: '2'}`

   537 

   538       * Route: `/file/*path`

   539         * URL: `/file/foo/bar/baz.txt`, params: `{path: 'foo/bar/baz.txt'}`

   540         * URL: `/file/foo`, params: `{path: 'foo'}`

   541 

   542     **Middleware**: Routes also support an arbitrary number of callback

   543     functions. This allows you to easily reuse parts of your route-handling code

   544     with different route. This method is liberal in how it processes the

   545     specified `callbacks`, you can specify them as separate arguments, or as

   546     arrays, or both.

   547 

   548     If multiple route match a given URL, they will be executed in the order they

   549     were added. The first route that was added will be the first to be executed.

   550 

   551     **Passing Control**: Invoking the `next()` function within a route callback

   552     will pass control to the next callback function (if any) or route handler

   553     (if any). If a value is passed to `next()`, it's assumed to be an error,

   554     therefore stopping the dispatch chain, unless that value is: `"route"`,

   555     which is special case and dispatching will skip to the next route handler.

   556     This allows middleware to skip any remaining middleware for a particular

   557     route.

   558 

   559     @example

   560         router.route('/photos/:tag/:page', function (req, res, next) {

   561             Y.log('Current tag: ' + req.params.tag);

   562             Y.log('Current page number: ' + req.params.page);

   563         });

   564 

   565         // Using middleware.

   566 

   567         router.findUser = function (req, res, next) {

   568             req.user = this.get('users').findById(req.params.user);

   569             next();

   570         };

   571 

   572         router.route('/users/:user', 'findUser', function (req, res, next) {

   573             // The `findUser` middleware puts the `user` object on the `req`.

   574             Y.log('Current user:' req.user.get('name'));

   575         });

   576 

   577     @method route

   578     @param {String|RegExp|Object} route Route to match. May be a string or a

   579       regular expression, or a route object.

   580     @param {Array|Function|String} callbacks* Callback functions to call

   581         whenever this route is triggered. These can be specified as separate

   582         arguments, or in arrays, or both. If a callback is specified as a

   583         string, the named function will be called on this router instance.

   584 

   585       @param {Object} callbacks.req Request object containing information about

   586           the request. It contains the following properties.

   587 

   588         @param {Array|Object} callbacks.req.params Captured parameters matched

   589           by the route path specification. If a string path was used and

   590           contained named parameters, then this will be a key/value hash mapping

   591           parameter names to their matched values. If a regex path was used,

   592           this will be an array of subpattern matches starting at index 0 for

   593           the full match, then 1 for the first subpattern match, and so on.

   594         @param {String} callbacks.req.path The current URL path.

   595         @param {Number} callbacks.req.pendingCallbacks Number of remaining

   596           callbacks the route handler has after this one in the dispatch chain.

   597         @param {Number} callbacks.req.pendingRoutes Number of matching routes

   598           after this one in the dispatch chain.

   599         @param {Object} callbacks.req.query Query hash representing the URL

   600           query string, if any. Parameter names are keys, and are mapped to

   601           parameter values.

   602         @param {Object} callbacks.req.route Reference to the current route

   603           object whose callbacks are being dispatched.

   604         @param {Object} callbacks.req.router Reference to this router instance.

   605         @param {String} callbacks.req.src What initiated the dispatch. In an

   606           HTML5 browser, when the back/forward buttons are used, this property

   607           will have a value of "popstate". When the `dispath()` method is

   608           called, the `src` will be `"dispatch"`.

   609         @param {String} callbacks.req.url The full URL.

   610 

   611       @param {Object} callbacks.res Response object containing methods and

   612           information that relate to responding to a request. It contains the

   613           following properties.

   614         @param {Object} callbacks.res.req Reference to the request object.

   615 

   616       @param {Function} callbacks.next Function to pass control to the next

   617           callback or the next matching route if no more callbacks (middleware)

   618           exist for the current route handler. If you don't call this function,

   619           then no further callbacks or route handlers will be executed, even if

   620           there are more that match. If you do call this function, then the next

   621           callback (if any) or matching route handler (if any) will be called.

   622           All of these functions will receive the same `req` and `res` objects

   623           that were passed to this route (so you can use these objects to pass

   624           data along to subsequent callbacks and routes).

   625         @param {String} [callbacks.next.err] Optional error which will stop the

   626           dispatch chaining for this `req`, unless the value is `"route"`, which

   627           is special cased to jump skip past any callbacks for the current route

   628           and pass control the next route handler.

   629     @chainable

   630     **/

   631     route: function (route, callbacks) {

   632         // Grab callback functions from var-args.

   633         callbacks = YArray(arguments, 1, true);

   634 

   635         var keys, regex;

   636 

   637         // Supports both the `route(path, callbacks)` and `route(config)` call

   638         // signatures, allowing for fully-processed route configs to be passed.

   639         if (typeof route === 'string' || YLang.isRegExp(route)) {

   640             // Flatten `callbacks` into a single dimension array.

   641             callbacks = YArray.flatten(callbacks);

   642 

   643             keys  = [];

   644             regex = this._getRegex(route, keys);

   645 

   646             route = {

   647                 callbacks: callbacks,

   648                 keys     : keys,

   649                 path     : route,

   650                 regex    : regex

   651             };

   652         } else {

   653             // Look for any configured `route.callbacks` and fallback to

   654             // `route.callback` for back-compat, append var-arg `callbacks`,

   655             // then flatten the entire collection to a single dimension array.

   656             callbacks = YArray.flatten(

   657                 [route.callbacks || route.callback || []].concat(callbacks)

   658             );

   659 

   660             // Check for previously generated regex, also fallback to `regexp`

   661             // for greater interop.

   662             keys  = route.keys;

   663             regex = route.regex || route.regexp;

   664 

   665             // Generates the route's regex if it doesn't already have one.

   666             if (!regex) {

   667                 keys  = [];

   668                 regex = this._getRegex(route.path, keys);

   669             }

   670 

   671             // Merge specified `route` config object with processed data.

   672             route = Y.merge(route, {

   673                 callbacks: callbacks,

   674                 keys     : keys,

   675                 path     : route.path || regex,

   676                 regex    : regex

   677             });

   678         }

   679 

   680         this._routes.push(route);

   681         return this;

   682     },

   683 

   684     /**

   685     Saves a new browser history entry and dispatches to the first matching route

   686     handler, if any.

   687 

   688     Behind the scenes, this method uses HTML5 `pushState()` in browsers that

   689     support it (or the location hash in older browsers and IE) to change the

   690     URL and create a history entry.

   691 

   692     The specified URL must share the same origin (i.e., protocol, host, and

   693     port) as the current page, or an error will occur.

   694 

   695     @example

   696         // Starting URL: http://example.com/

   697 

   698         router.save('/path/');

   699         // New URL: http://example.com/path/

   700 

   701         router.save('/path?foo=bar');

   702         // New URL: http://example.com/path?foo=bar

   703 

   704         router.save('/');

   705         // New URL: http://example.com/

   706 

   707     @method save

   708     @param {String} [url] URL to set. This URL needs to be of the same origin as

   709       the current URL. This can be a URL relative to the router's `root`

   710       attribute. If no URL is specified, the page's current URL will be used.

   711     @chainable

   712     @see replace()

   713     **/

   714     save: function (url) {

   715         return this._queue(url);

   716     },

   717 

   718     /**

   719     Upgrades a hash-based URL to an HTML5 URL if necessary. In non-HTML5

   720     browsers, this method is a noop.

   721 

   722     @method upgrade

   723     @return {Boolean} `true` if the URL was upgraded, `false` otherwise.

   724     **/

   725     upgrade: function () {

   726         if (!this._html5) {

   727             return false;

   728         }

   729 

   730         // Get the resolve hash path.

   731         var hashPath = this._getHashPath();

   732 

   733         if (hashPath) {

   734             // This is an HTML5 browser and we have a hash-based path in the

   735             // URL, so we need to upgrade the URL to a non-hash URL. This

   736             // will trigger a `history:change` event, which will in turn

   737             // trigger a dispatch.

   738             this.once(EVT_READY, function () {

   739                 this.replace(hashPath);

   740             });

   741 

   742             return true;

   743         }

   744 

   745         return false;

   746     },

   747 

   748     // -- Protected Methods ----------------------------------------------------

   749 

   750     /**

   751     Wrapper around `decodeURIComponent` that also converts `+` chars into

   752     spaces.

   753 

   754     @method _decode

   755     @param {String} string String to decode.

   756     @return {String} Decoded string.

   757     @protected

   758     **/

   759     _decode: function (string) {

   760         return decodeURIComponent(string.replace(/\+/g, ' '));

   761     },

   762 

   763     /**

   764     Shifts the topmost `_save()` call off the queue and executes it. Does

   765     nothing if the queue is empty.

   766 

   767     @method _dequeue

   768     @chainable

   769     @see _queue

   770     @protected

   771     **/

   772     _dequeue: function () {

   773         var self = this,

   774             fn;

   775 

   776         // If window.onload hasn't yet fired, wait until it has before

   777         // dequeueing. This will ensure that we don't call pushState() before an

   778         // initial popstate event has fired.

   779         if (!YUI.Env.windowLoaded) {

   780             Y.once('load', function () {

   781                 self._dequeue();

   782             });

   783 

   784             return this;

   785         }

   786 

   787         fn = saveQueue.shift();

   788         return fn ? fn() : this;

   789     },

   790 

   791     /**

   792     Dispatches to the first route handler that matches the specified _path_.

   793 

   794     If called before the `ready` event has fired, the dispatch will be aborted.

   795     This ensures normalized behavior between Chrome (which fires a `popstate`

   796     event on every pageview) and other browsers (which do not).

   797 

   798     @method _dispatch

   799     @param {object} req Request object.

   800     @param {String} res Response object.

   801     @chainable

   802     @protected

   803     **/

   804     _dispatch: function (req, res) {

   805         var self      = this,

   806             decode    = self._decode,

   807             routes    = self.match(req.path),

   808             callbacks = [],

   809             matches, paramsMatch, routePath;

   810 

   811         self._dispatching = self._dispatched = true;

   812 

   813         if (!routes || !routes.length) {

   814             self._dispatching = false;

   815             return self;

   816         }

   817 

   818         routePath = self.removeRoot(req.path);

   819 

   820         function next(err) {

   821             var callback, name, route;

   822 

   823             if (err) {

   824                 // Special case "route" to skip to the next route handler

   825                 // avoiding any additional callbacks for the current route.

   826                 if (err === 'route') {

   827                     callbacks = [];

   828                     next();

   829                 } else {

   830                     Y.error(err);

   831                 }

   832 

   833             } else if ((callback = callbacks.shift())) {

   834                 if (typeof callback === 'string') {

   835                     name     = callback;

   836                     callback = self[name];

   837 

   838                     if (!callback) {

   839                         Y.error('Router: Callback not found: ' + name, null, 'router');

   840                     }

   841                 }

   842 

   843                 // Allow access to the number of remaining callbacks for the

   844                 // route.

   845                 req.pendingCallbacks = callbacks.length;

   846 

   847                 callback.call(self, req, res, next);

   848 

   849             } else if ((route = routes.shift())) {

   850                 // Make a copy of this route's `callbacks` so the original array

   851                 // is preserved.

   852                 callbacks = route.callbacks.concat();

   853 

   854                 // Decode each of the path matches so that the any URL-encoded

   855                 // path segments are decoded in the `req.params` object.

   856                 matches = YArray.map(route.regex.exec(routePath) || [],

   857                         function (match) {

   858 

   859                     // Decode matches, or coerce `undefined` matches to an empty

   860                     // string to match expectations of working with `req.params`

   861                     // in the content of route dispatching, and normalize

   862                     // browser differences in their handling of regex NPCGs:

   863                     // https://github.com/yui/yui3/issues/1076

   864                     return (match && decode(match)) || '';

   865                 });

   866 

   867                 paramsMatch = true;

   868 

   869                 // Use named keys for parameter names if the route path contains

   870                 // named keys. Otherwise, use numerical match indices.

   871                 if (matches.length === route.keys.length + 1) {

   872                     matches    = matches.slice(1);

   873                     req.params = YArray.hash(route.keys, matches);

   874 

   875                     paramsMatch = YArray.every(route.keys, function (key, i) {

   876                         var paramHandler = self._params[key],

   877                             value        = matches[i];

   878 

   879                         if (paramHandler && value && typeof value === 'string') {

   880                             // Check if `paramHandler` is a RegExp, becuase this

   881                             // is true in Android 2.3 and other browsers!

   882                             // `typeof /.*/ === 'function'`

   883                             value = YLang.isRegExp(paramHandler) ?

   884                                     paramHandler.exec(value) :

   885                                     paramHandler.call(self, value, key);

   886 

   887                             if (value !== false && YLang.isValue(value)) {

   888                                 req.params[key] = value;

   889                                 return true;

   890                             }

   891 

   892                             return false;

   893                         }

   894 

   895                         return true;

   896                     });

   897                 } else {

   898                     req.params = matches.concat();

   899                 }

   900 

   901                 // Allow access to current route and the number of remaining

   902                 // routes for this request.

   903                 req.route         = route;

   904                 req.pendingRoutes = routes.length;

   905 

   906                 // Execute this route's `callbacks` or skip this route because

   907                 // some of the param regexps don't match.

   908                 if (paramsMatch) {

   909                     next();

   910                 } else {

   911                     next('route');

   912                 }

   913             }

   914         }

   915 

   916         next();

   917 

   918         self._dispatching = false;

   919         return self._dequeue();

   920     },

   921 

   922     /**

   923     Returns the resolved path from the hash fragment, or an empty string if the

   924     hash is not path-like.

   925 

   926     @method _getHashPath

   927     @param {String} [hash] Hash fragment to resolve into a path. By default this

   928         will be the hash from the current URL.

   929     @return {String} Current hash path, or an empty string if the hash is empty.

   930     @protected

   931     **/

   932     _getHashPath: function (hash) {

   933         hash || (hash = HistoryHash.getHash());

   934 

   935         // Make sure the `hash` is path-like.

   936         if (hash && hash.charAt(0) === '/') {

   937             return this._joinURL(hash);

   938         }

   939 

   940         return '';

   941     },

   942 

   943     /**

   944     Gets the location origin (i.e., protocol, host, and port) as a URL.

   945 

   946     @example

   947         http://example.com

   948 

   949     @method _getOrigin

   950     @return {String} Location origin (i.e., protocol, host, and port).

   951     @protected

   952     **/

   953     _getOrigin: function () {

   954         var location = Y.getLocation();

   955         return location.origin || (location.protocol + '//' + location.host);

   956     },

   957 

   958     /**

   959     Getter for the `params` attribute.

   960 

   961     @method _getParams

   962     @return {Object} Mapping of param handlers: `name` -> RegExp | Function.

   963     @protected

   964     @since 3.12.0

   965     **/

   966     _getParams: function () {

   967         return Y.merge(this._params);

   968     },

   969 

   970     /**

   971     Gets the current route path.

   972 

   973     @method _getPath

   974     @return {String} Current route path.

   975     @protected

   976     **/

   977     _getPath: function () {

   978         var path = (!this._html5 && this._getHashPath()) ||

   979                 Y.getLocation().pathname;

   980 

   981         return this.removeQuery(path);

   982     },

   983 

   984     /**

   985     Returns the current path root after popping off the last path segment,

   986     making it useful for resolving other URL paths against.

   987 

   988     The path root will always begin and end with a '/'.

   989 

   990     @method _getPathRoot

   991     @return {String} The URL's path root.

   992     @protected

   993     @since 3.5.0

   994     **/

   995     _getPathRoot: function () {

   996         var slash = '/',

   997             path  = Y.getLocation().pathname,

   998             segments;

   999 

  1000         if (path.charAt(path.length - 1) === slash) {

  1001             return path;

  1002         }

  1003 

  1004         segments = path.split(slash);

  1005         segments.pop();

  1006 

  1007         return segments.join(slash) + slash;

  1008     },

  1009 

  1010     /**

  1011     Gets the current route query string.

  1012 

  1013     @method _getQuery

  1014     @return {String} Current route query string.

  1015     @protected

  1016     **/

  1017     _getQuery: function () {

  1018         var location = Y.getLocation(),

  1019             hash, matches;

  1020 

  1021         if (this._html5) {

  1022             return location.search.substring(1);

  1023         }

  1024 

  1025         hash    = HistoryHash.getHash();

  1026         matches = hash.match(this._regexUrlQuery);

  1027 

  1028         return hash && matches ? matches[1] : location.search.substring(1);

  1029     },

  1030 

  1031     /**

  1032     Creates a regular expression from the given route specification. If _path_

  1033     is already a regex, it will be returned unmodified.

  1034 

  1035     @method _getRegex

  1036     @param {String|RegExp} path Route path specification.

  1037     @param {Array} keys Array reference to which route parameter names will be

  1038       added.

  1039     @return {RegExp} Route regex.

  1040     @protected

  1041     **/

  1042     _getRegex: function (path, keys) {

  1043         if (YLang.isRegExp(path)) {

  1044             return path;

  1045         }

  1046 

  1047         // Special case for catchall paths.

  1048         if (path === '*') {

  1049             return (/.*/);

  1050         }

  1051 

  1052         path = path.replace(this._regexPathParam, function (match, operator, key) {

  1053             // Only `*` operators are supported for key-less matches to allowing

  1054             // in-path wildcards like: '/foo/*'.

  1055             if (!key) {

  1056                 return operator === '*' ? '.*' : match;

  1057             }

  1058 

  1059             keys.push(key);

  1060             return operator === '*' ? '(.*?)' : '([^/#?]*)';

  1061         });

  1062 

  1063         return new RegExp('^' + path + '$');

  1064     },

  1065 

  1066     /**

  1067     Gets a request object that can be passed to a route handler.

  1068 

  1069     @method _getRequest

  1070     @param {String} src What initiated the URL change and need for the request.

  1071     @return {Object} Request object.

  1072     @protected

  1073     **/

  1074     _getRequest: function (src) {

  1075         return {

  1076             path  : this._getPath(),

  1077             query : this._parseQuery(this._getQuery()),

  1078             url   : this._getURL(),

  1079             router: this,

  1080             src   : src

  1081         };

  1082     },

  1083 

  1084     /**

  1085     Gets a response object that can be passed to a route handler.

  1086 

  1087     @method _getResponse

  1088     @param {Object} req Request object.

  1089     @return {Object} Response Object.

  1090     @protected

  1091     **/

  1092     _getResponse: function (req) {

  1093         return {req: req};

  1094     },

  1095 

  1096     /**

  1097     Getter for the `routes` attribute.

  1098 

  1099     @method _getRoutes

  1100     @return {Object[]} Array of route objects.

  1101     @protected

  1102     **/

  1103     _getRoutes: function () {

  1104         return this._routes.concat();

  1105     },

  1106 

  1107     /**

  1108     Gets the current full URL.

  1109 

  1110     @method _getURL

  1111     @return {String} URL.

  1112     @protected

  1113     **/

  1114     _getURL: function () {

  1115         var url = Y.getLocation().toString();

  1116 

  1117         if (!this._html5) {

  1118             url = this._upgradeURL(url);

  1119         }

  1120 

  1121         return url;

  1122     },

  1123 

  1124     /**

  1125     Returns `true` when the specified `url` is from the same origin as the

  1126     current URL; i.e., the protocol, host, and port of the URLs are the same.

  1127 

  1128     All host or path relative URLs are of the same origin. A scheme-relative URL

  1129     is first prefixed with the current scheme before being evaluated.

  1130 

  1131     @method _hasSameOrigin

  1132     @param {String} url URL to compare origin with the current URL.

  1133     @return {Boolean} Whether the URL has the same origin of the current URL.

  1134     @protected

  1135     **/

  1136     _hasSameOrigin: function (url) {