#Backbone Subroute

##About

Backbone's Router feature is really powerful, but for large multi-module apps, it can quickly become large and unmaintainable.

Backbone.SubRoute extends the functionality of Backbone.Router such that each of an application's modules can define its own module-specific routes. This eliminates the need for one monolithic Router configuration, The base router can instead act as a simple delegator that forwards module-specific routes to the appropriate module-specific SubRoute.

For example, given this URL: http:example.org/myModule/foo/bar

...the base router would be responsible for invoking and delegating to the proper module based on "myModule". The module would then have its own SubRoute which would have its own mappings for the foo/bar part.

This project is based on a Gist by Tim Branyen, and used with permission from the original author.

Get Involved!

Mailing List

Join the Backbone.Subroute Google Group to discuss new features and stay-up-to-date on project updates.

Contributions

Contributions are greatly appreciated! For best results:

• Please submit a failing test spec with any issue reports.
• Please submit passing test specs for new features.

##Usage

jam install backbone.subroute

Defining a SubRouter

Let's say that you've got a section of your web app multiple pieces of functionality all live under the URL prefix http://yourserver.org/books. Here's how you'd create your subrouter.

var BooksRouter = Backbone.SubRoute.extend({
    routes: {
        ""               : "showBookstoreHomepage", 
        "search"         : "searchBooks",           
        "view/:bookId"   : "viewBookDetail",        
    },
    showBookstoreHomepage: function() {
        // ...module-specific code
    },
    searchBooks: function() {
        // ...module-specific code
    },
    viewBookDetail: function(bookId) {
        // ...module-specific code using bookId param
    }
});

Note that the subrouter, itself, doesn't know or care what its prefix is. The prefix is only provided when instantiating specific instances of the sub-router. This makes sub-routers especially useful for reusing common pieces of code.

Creating an Instance

To use your sub-router, siply call its constructor and provide a prefix, like so:

var mySubRouteInstance = new BooksRouter("books");

Understanding The Magic

Given the example above, with an instance of the sub-route being created with the "books" argument passed as a constructor, and deployed on a server with a base URL of yourserver.org, this results in the following routes being created:

Subroute	Expands To	Matches URL
""	books	http://yourserver.org/books
"search"	books/search	http://yourserver.org/books/search
"view/:bookId"	books/view/:bookId	http://yourserver.org/books/view/1234

Passing Parameters to SubRouter Instances

When instantiating a SubRouter, you may wish to provide some parameters from the calling code, which may be needed in your sub-router code. The sub-router constructor takes an optional object literal as a second argument.

For instance:

var mySubRouteInstance = new BooksRouter("books", {locale: "en_US", isVIP: true));

Then in your sub-router definition, you can access these parameters using the familiar Backbone options object, used in other Backbone components. Like so:

initialize: function(options) {
    this.locale = options.locale;
    this.isVIP = options.isVIP;
}

Thanks to @carpeliam for this feature.

Trailing Slashes

Backbone treats routes with trailing slashes as totally different routes than those without. For instance, these are two different routes in Backbone:

"search"

"search/"

URL semantics aside, many people have found this behavior annoying. If you're one of them, and you want to support either format without duplicating each and every one of your routes, you can pass the optional createTrailingSlashRoutes parameter when you instantiate your sub-router.

For example:

var mySubRouteInstance = new BooksRouter("books", {createTrailingSlashRoutes: true));

Using the examples above, a URL of either http://yourserver.org/books/search or http://yourserver.org/books/search/ would fire the searchBooks() callback.

Unit Tests

The spec directory in the repo contains a suite of test specs. To run them, start a web server in the project directory, then point your browser to the spec directory.

The test specs can also be run online here.

More Examples

See my blog post for detailed instructions on how to set up and use your sub-routes.

Version History

0.3.2

Released 22 Jan 2013

• Skip call to loadUrl on SubRoute init if history hash does not match SubRoute prefix

0.3.1

Released 26 October 2012

• Fixed Issue #13. This was an IE8-only issue where manually including a trailing slash in a subroute prefix caused a double slash to appear in the fully-qualified route. Thanks to @mikesnare for logging the issue and providing the fix!
• Added Jasmine test specs for above case

0.3

Released 30 August 2012

• Fixed issue in navigate method where separator / character was omitted after prefix
• Added Jasmine test specs

0.2

Released 15 July 2012

• AMD support
• Added createTrailingSlashRoutes property
• No longer append trailing slash to route prefix (to support default empty-string routes)
• Robust handling of subroute path creation, supporting prefixes with and without trailing slashes

0.1

Released 16 April 2012

• Initial version based on Tim's gist, with a fix for invoking a subroute on first load

##License The MIT License (MIT)

Copyright (c) 2012 Model N, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.