backbone.base-router

backbone.base-router

A better starting point for creating your own routing abstractions in Backbone.

What problems does this library solve?

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.

What problems doesn't this library solve?

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.

• Getting Started
  • The Single Point of Entry
  • Removed Features
  • Example Usage
• API
  • history
  • onNavigate

Getting Started

The Single Point of Entry

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.

Removed features

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.

Example Usage

See the examples/ directory. There are READMEs for each example.

API

onNavigate( routeData )

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.

routeData

linked

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.

route

The regular expression that matched the URI fragment.

originalRoute

If the route was registered as a string, and not a regular expression, then this will be that original string. Otherwise, it is undefined.

params

An object which has keys that are the named parameters from the Route, and corresponding values from the URL.

query

An object representation of the query string in the URI fragment.

router

The router instance that this route was registered on.

uriFragment

The URI fragment that was matched.

Changelog

1.0.0

• Enhancement: Adds support for multiple query parameters of the same name. They are returned as an array.