A better starting point for creating your own routing abstractions in Backbone.
Backbone's Router has two frustrating properties: it is too simple and too difficult to change. This library solves the second problem to make it easier for you to solve the first problem.
Instead of requiring that you associate a callback with a route, this library lets you associate whatever you'd like with a route. It can be a callback if you want, but it can also be an object, or even a string.
Whenever a Route is matched, a single method on the Router is called. This method is passed a single
argument, routeData, that contains as much about the matched route as possible. Included this object are parsed
query parameters, named fragment params, and the object you associated with the route, among other things. This
single point-of-entry, combined with all of this data, makes it remarkably easy to add new abstractions to the Router.
This library is not an effort to rewrite Backbone.history. As such, some of History's quirks are carried
over, too. For instance, the order that you specify your callbacks in still matters, as this is how Backbone.History matches routes.
The API for the Base Router is simple: there's a single callback that gets called when a Route is navigated to. This callback is a plethora of information you might need, such as parsed query parameters and whatever object was associated with the callback. This is the location where you build your abstractions from.
Backbone.BaseRouter does more for you by doing less. The following features were removed from the router.
- A callback, if specified, is not automatically executed
- No routing-related events are fired
The point of removing these features is that it gives you complete control over the Routing mechanism. It's simple to add them back in. Or you can change them to be exactly how you want. Or just leave them out. It's entirely up to you.
See the examples/ directory. There are READMEs for each example.
The single point of entry is the onNavigate method. This method is called each time the user navigates
via Backbone.history.
// Create a new Base Router
var router = new BaseRouter();
// Each time the user navigates to a matched route, a console message
// logs all of the data passed to the callback.
router.onNavigate = function(routeData) {
console.log('The user has navigated!', routeData);
};In addition to being called everytime that the user navigates to a matched route, which in itself is useful, the
callback is passed a plethora of useful data related to the navigation action. This information is contained
in the routeData argument.
The object that was associated with this route. In a traditional Backbone router, this is always a callback that is executed. In the BaseRouter, this can be anything, and no assumptions are made about what you should do with it.
The regular expression that matched the URI fragment.
If the route was registered as a string, and not a regular expression, then this will be that original string. Otherwise, it is undefined.
An object which has keys that are the named parameters from the Route, and corresponding values from the URL.
An object representation of the query string in the URI fragment.
The original query string in the URI fragment. undefined if no query string given
The router instance that this route was registered on.
The URI fragment that was matched.