#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.
Subroute is lightweight, weighing in at under 300 bytes minified and gzipped.
Latest Stable Release: 0.4.5
- Minified: backbone.subroute.min.js
- Development (Uncompressed, Comments): backbone.subroute.js
- Full Release (Tests, Examples): 0.4.5.zip.
Unreleased Edge Version (master)
- Minified: backbone.subroute.min.js
- Development (Uncompressed, Comments): backbone.subroute.js
- Full Release (Tests, Examples): master.zip.
Visit the project repo to download the latest unreleased code (may be unstable).
Join the Backbone.Subroute Google Group to discuss new features and stay-up-to-date on project updates.
Has Subroute been helpful to you? If you'd like to give back, here are a few ways:
- Blog about your experiences using Subroute, and let us know about it!
- Create a demo app using Subroute and add it to the repo.
- Improve the docs in the README.
- Fix a bug or add a new feature and submit a pull request (see below)
Pull requests are welcome. For any significant change or new feature, please start a discussion in the Google Group, or log an issue first. This will save you some time, in case your idea is deemed not general enough to be included in the project.
Before submitting a pull request, please:
- Write unit tests to cover any new or modified lines of code, and add it to the
specs/
directory. See the Testing section for more info. - Run the test specs to make sure everything works. You can fire up a local web server, and point your browser to
http://localhost:<port>/spec/
- Run the Grunt task to lint, test, and run code coverage on the project. See the Build section for more info.
Subroute uses Grunt to verify each build. If you are not familiar with Grunt, check out the getting started guide for an introduction and installation instructions.
Before submitting a pull request, please run the grunt task. To do so:
First, install local development dependencies. From the root Subroute directory, run:
npm install
then
grunt
Grunt will perform these tasks:
- Beautify
To reduce merging and styling issues related to whitespace and formatting, the jsbeautifier task normalizes all formatting in project source. If you fail to run grunt
prior to check-in, and any files have not been beautified, Travis-CI will reject the checkin.
- Uglify
The code will be minified and saved to dist/backbone.subroute.min.js
.
- Lint
Javascript files are checked for errors using JSHint. The JSLint configuration is driven by the .jshintrc
file.
- Test
Test specs are run headlessly using PhantomJS
- Coverage
Code coverage is enforced using Istanbul. Currently not every feature of Subroute has coverage.
But the enforced coverage levels are set such that code coverage cannot decrease. Over time, more tests will be added to increase coverage
to as close to 100% as possible (help with this is greatly appreciated!)
The Grunt build is run automatically using Travis-CI upon every pull request and push to master. But if any errors are found, you'll need to fix them and re-submit your pull request. So please run the grunt task locally to save time.
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.
To use your sub-router, simply call its constructor and provide a prefix, like so:
var mySubRouteInstance = new BooksRouter("books");
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 |
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.
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.
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.
- See my blog post for a walkthrough of setting up subroutes for an online shopping site.
- Swizec Teller wrote a great piece about how his team used subroutes to simplify a complex multi-module architecture.
Released 13 October 2014
- Actually export the router when used as CommonJS module (Thanks, xMartin!)
Released 1 September 2014
- Add official bower support
- Add grunt-version to dev dependencies
Released 9 May 2014
- Fix issue 38 due to minified dist file being out-of-sync from latest source.
Released 7 April 2014
- Fix issues with dynamic route creation. Thanks @hellorachid for the fix!
- Allow empty prefix. Thanks to @maoueh for the PR!
- Support for CommonJS thanks to @gdw2's work.
- Published on NPM thanks to @thejameskyle's prep work.
Released 23 September 2013
- Fix Issue #27, which caused multiple instances of the same subrouter class to get polluted with each others routes in their
routes
hash. Big thanks to @mikesnare for suggesting the fix, and @joshuaballoch for providing the specs to identify the issue.
Released 17 July 2013
- Fix Issue #22, a bug that would cause initial loading to not happen correctly if prefix contained parameters. Thanks, @whyohwhyamihere for the PR!
- Add build support using Grunt
Released 22 January 2013
- Skip call to loadUrl on SubRoute init if history hash does not match SubRoute prefix
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
Released 30 August 2012
- Fixed issue in
navigate
method where separator/
character was omitted after prefix - Added Jasmine test specs
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
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.