Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Better route management for Backbone.js projects.
JavaScript
branch: master

README.md

backbone.routemanager

Created by Tim Branyen @tbranyen

Provides missing features to the Backbone.Router.

Depends on Underscore, Backbone and jQuery. You can swap out the jQuery dependency completely with a custom configuration.

Tutorials and Screencasts

Download & Include

Development is fully commented source, Production is minified and stripped of all comments except for license/credits.

Include in your application after jQuery, Underscore, and Backbone have been included.

<script src="/js/jquery.js"></script>
<script src="/js/underscore.js"></script>
<script src="/js/backbone.js"></script>

<script src="/js/backbone.routemanager.js"></script>

Usage

Defining a RouteManager

A route manager is your App Router, you will be able to define any number of Nested Routers.

Assuming you have an app namespace

// A basic route manager, works just like a Backbone.Router (cause it is one)
var AppRouter = Backbone.RouteManager.extend({
  routes: {
    "": "index"
  },

  index: function() {
    window.alert("Navigated successfully");
  }
});

// Create a new instance of the app router
app.router = new AppRouter();

// Trigger the index route
app.router.navigate("", true);

Alternative method of defining a RouteManager

If you don't wish to extend the Backbone.RouteManager you can simply make a new instance of the constructor and assign that to save yourself a step.

// A basic route manager, works just like a Backbone.Router (cause it is one)
app.router = new Backbone.RouteManager({
  routes: {
    "": "index"
  },

  index: function() {
    window.alert("Navigated successfully");
  }
});

// Trigger the index route
app.router.navigate("", true);

Named params object

All route callbacks get access to a special object on the Router called params which maps directly to the variables and splats defined in the route.

// A basic route manager, works just like a Backbone.Router (cause it is one)
var AppRouter = new Backbone.RouteManager({
  routes: {
    ":id/*path": "index"
  },

  index: function(id, path) {
    // You can use the arbitrarily named args you define... or you can use the
    // params object on the router.
    window.alert(id == this.params.id);
    window.alert(path == this.params.path);
  }
});

// Create a new instance of the app router
app.router = new AppRouter();

// Trigger the index route
app.router.navigate("5/hi", true);

This is useful for a number of reasons including a special significance for before/after filters that are defined later on.

Nested Routers

So far we haven't seen anything special that we couldn't do already with a normal Backbone.Router. One of the major benefits of RouteManager is that you can define nested Routers. These are defined in the same way as normal routes, except you pass a Backbone.Router class instead.

Nested Routers are just normal Backbone.Router's.

For example:

var SubRouter = Backbone.Router.extend({
  routes: {
    "": "index",
    "test": "test"
  },

  index: function() {
    window.alert("SubRouter navigated successfully");
  },

  test: function() {
    window.alert("sub/test triggered correctly");
  }
});

var AppRouter = Backbone.RouteManager.extend({
  routes: {
    // Define a root level route
    "": "index",

    // Define a sub route
    "sub/": SubRouter
  },

  index: function() {
    window.alert("MasterRouter navigated successfully");
  }
});

// Create a new instance of the app router
app.router = new AppRouter();

// Trigger the test route under sub
app.router.navigate("sub/test", true);

Before/After filters

The real meat of RouteManager, besides the nested Routers, is the ability to define functions to be run before and after a route has fired. This has huge benefits for keeping your Router DRY and flexible.

To define a before and after filter, simply create respectively named objects on your Router along with a key/val set matching routes and callbacks.

The this context inside the filter functions is different from the route callback. this is a special object that can put the function in async/defer mode (which is discussed later). It has a reference to the router that can be accessed with this.router if you wish to store properties or access it.

Backbone.Router.extend({
  before: {
    "": ["auth", "layout"]
  },

  after: {
    "": ["render"]
  }

  routes: {
    "": "index"
  },

  // Before callbacks
  auth: function() {}
  layout: function() {}

  // Route callbacks
  index: function() {}

  // After callbacks
  render: function() {}
});

Params => arguments mapping

Your filter functions may need to be callable from outside of the RouteManager filter environment. Therefore no automatic mapping is possible, but there is a very simple boolean logic assignment that you can make that ensures your functions are correctly callable.

Backbone.Router.extend({
  before: {
    "user/:id": ["getUser"]
  },

  routes: {
    "": "index"
  },

  // Before callbacks
  getUser: function(id) {
    id = id || this.params.id;

    // id maps to this.params.id or whatever value is passed in
    console.log(id);
  }

  // Route callbacks
  index: function() {}
});

Because of this check you can now do something like this:

// Since you are calling this function on its own, the id will be mapped to
// whatever value you'd like, without needing `this.params`.
router.getUser(5);

There are three different types of functions that can be put inside the filters array: Synchronous, Asynchronous, and Promise/Deferreds. These can be mixed and matched together to create a logical and performant flow to your route.

Filters run sequentially and will always block the next function until they are complete. This means if you have ["a","b","c"] as your array of callbacks, a will have to complete before b is executed. The only exception to this is when a Promise/Deferred is encountered and added to the list to resolve.

If you wish to stop the chain at any point (subsequently stopping the route callback from triggering as well), you can do this in a number of ways depending on the type of filter. Each way is discussed in the respective section.

Synchronous filters

These are the most basic filter and require nothing special to use. Just create normal functions that should be executed before a route.

Backbone.Router.extend({
  before: {
    "": ["sync"]
  },

  sync: function() {
    console.log("this runs before index");
  },

  routes: {
    "": "index"
  }
});

To signify an error in your synchronous function to cause remaining functions to not be called, simply return false in your function.

  sync: function() {
    console.log("not going to run any more filter functions");

    return false;
  },

Asynchronous filters

When your code is affected by a non-blocking call (think XHR, setTimeout, etc), the above synchronous definition cannot work, as there would be no way to tell RouteManager when the function is done.

To put the function into asynchronous mode simply assign a done callback with var done = this.async() and call done() when you are finished in the function.

Backbone.Router.extend({
  before: {
    "": ["sync", "async"]
  },

  ...,

  async: function() {
    var done = this.async();

    window.setTimeout(function() {
      console.log("this runs after sync and before index");

      // Progress to the next 
      done();
    }, 1000);
  },

  routes: {
    "": "index"
  }
});

To signify an error in your asynchronous function to cause remaining functions to not be called, simply call done with false.

  async: function() {
    var done = this.async();

    window.setTimeout(function() {
      console.log("this runs after sync and never calls index");

      // Do not progress to the next
      done(false);
    }, 1000);
  },

Deferred/Promise filters

There may be times that you will work with asynchronous code that can be run in parallel. The deferred filter mode was designed for this use case.
When RouteManager encounters a deferred filter it puts it into a bucket and continues on to the next function, it will continue grouping all deferreds until it hits a non-deferred in which it will wait till they resolve and then execute.

To put a filter function into the deferred mode, simply assign this.defer to a variable and call resolve or reject when its finished.

Backbone.Router.extend({
  before: {
    "": ["sync", "async", "defer"]
  },

  ...,

  defer: function() {
    var deferred = this.defer();

    window.setTimeout(function() {
      console.log("this runs after sync, async, and before index");

      // Progress to the next 
      deferred.resolve();
    }, 1000);
  },

  routes: {
    "": "index"
  }
});

It may be useful to leverage an existing deferred instead of creating a new one. This is particularly useful when calling fetch on models and collections. Simply pass the deferred to defer and it will be used internally.

defer: function() {
  this.defer(collection.fetch());
}

To signify an error in your deferred function to cause remaining functions to not be called, simply call reject on the deferred.

  defer: function() {
    var deferred = this.defer();

    window.setTimeout(function() {
      console.log("this runs after sync, async, and stops index");

      // Do not progress to the next 
      deferred.reject();
    }, 1000);
  },

Configuration

Overriding RouteManager options has been designed to work just like Backbone.sync. You can override at a global level using RouteManager.configure or you can specify when instantiating a RouteManager instance.

Global level

Lets say you wanted to use underscore.deferred for the Promise lib instead of jQuery.

// Override all RouteManagers to use underscore.deferred
Backbone.RouteManager.configure({
  deferred: function() {
    return new _.Deferred();
  },

  when: function(promises) {
    return _.when.apply(null, promises);
  }
});

Instance level

In this specific router, use underscore.deferred for the Promise lib instead of jQuery.

app.router = new Backbone.RouteManager({
  routes: {
    "": "index"
  },

  options: {
    deferred: function() {
      return new _.Deferred();
    },

    when: function(promises) {
      return _.when.apply(null, promises);
    }
  }
});

Defaults

  • Deferred: Uses jQuery deferreds for internal operation, this may be overridden to use a different Promises/A compliant deferred.
deferred: function() {
  return $.Deferred();
}
  • When: This function will trigger callbacks based on the success/failure of one or more deferred objects.
when: function(promises) {
  return $.when.apply(null, promises);
}

Release History

Something went wrong with that request. Please try again.