jamesplease / backbone.base-router

A better starting point for building a new Backbone 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.

queryString

The original query string in the URI fragment. undefined if no query string given

router

The router instance that this route was registered on.

uriFragment

The URI fragment that was matched.

backbone.base-router's Issues

Support route removal and insert-at

An API for more flexible dynamically-constructed routers would be quite powerful. This would enable subclasses to implement a modular router paradigm while keeping order intact when it counts, such as the soft-404 handler. The implementation would essentially boil down to splicing on the undocumented Backbone.history.handlers array. Or, like you mention in #22, the alternative may be a rewrite of Backbone.history.

Possible use case:

• Allow for dynamic registering/deregistering routes without conflicting with a catch-all terminal route, such as a soft-404 handler

Possible API

• Backbone.history.insertBefore(route, referenceRoute)
• Backbone.history.insertAfter(route, referenceRoute)
• Backbone.history.insertAt(route, index)
• Backbone.history.remove(route or index)

Note that route removal and insert-at could be rendered unnecessary if this library departs from Backbone.History "callback order" entirely. Perhaps that is the question that should be answered first, whether or not this library will become "an effort to rewrite Backbone.history" after all.

Use prototype constructor

❌

Store regex at top of file

• https://github.com/jmeas/backbone.base-router/blob/master/src/backbone.base-router.js#L80
• https://github.com/jmeas/backbone.base-router/blob/master/src/backbone.base-router.js#L92

Figure out what it takes to support earlier versions of Backbone

1.1.x support is lousy

Double use strict

Remove it from the src file.

Update coverage script

ref jamesplease/backbone.overlay-view#5

Any objections to bumping backbone version to 1.3.3?

Move route params off prototype

Support canceling routes on navigate

Canceling routes should be possible, but the interaction between the BB.History and the registered routes makes this a non-trivial task.

The registered Route should determine whether it can be canceled or not. And the act of canceling needs to happen before history updates the URI. Yet the Router sends over a callback that does not have knowledge of the linked object...only the Router ever knows about the link.

I might need to rewrite history/routing altogether to do this.

Upgrade dependencies

Same issue as with Intercept, the outdated dependencies are screwing up Webpack builds.

Overwrite navigate function

Let users type in the params and queries in object notation.

Examples too simple

The example folder should be enlarged with more complex application. It doesn't show advanced features / how it can be used in multiple module app.

Add npm scripts

So that developers don't need to have Grunt installed globally

Parse array query params