Backbone.Highway - Routing Backbone with style \o/
Backbone.Highway
wraps the Backbone.Router
to simplify its use and bring new functionalities.
Added functionalities compared to the Backbone.Router
are:
- Named routes
- Catching client-size 404
- Before/After Middlewares
- Before/After event triggers distributed using an event aggregator
- Async flow control using JavaScript
Promise
Installation
npm install --save backbone-highway
or
bower install --save backbone-highway
Getting started
Simply declare some routes using the highway.route()
method
and then start the router with the highway.start()
method.
// Declare a home routehighway // Declare a user profile routehighway // Start the routerhighwaystart
highway.route()
Declaring a route highway
A route is at least composed of a name
, path
and action
, like it is shown the example above.
The name
and path
need to be uniq to prevent conflicting routes which can lead to unexpected behavior.
Note: The path of the route needs to be declared with a leading slash to properly work in highway
. For now, the regular expression format has not been tested, it may or may not work.
The action
needs to be a function
which will receive an Object
as its only argument.
This state
object will contain:
params
with the parameters received from parsing the dynamic parts of thepath
.resolve
andreject
methods to control the flow of execution of the route.
route
method
Options for the name {string}
The uniq name of the routepath {string}
The path of the route as described in the Backbone documentationaction {function}
The controller method for this routebefore {array}
Optional A list of events or middlewares to be executed before theaction
after {array}
Optional A list of events or middlewares to be executed after theaction
if it is resolved
highway.start()
Starting the router Backbone.Highway
uses sensible defaults that can be overriden by passing an options object to the start method.
Here are the default options provided by the library :
highwaystart // # Backbone History options // Docs: http://backbonejs.org/#History // Use html5 pushState pushState: true // Root url for pushState root: '' // Set to false to force page reloads for old browsers hashChange: true // Don't trigger the initial route silent: false // # Backbone.Highway specific options // Print out debug information debug: false // Event aggregator instance dispatcher: null
highway.go()
Navigating Use the go
method to navigate programmatically to a declared route
// Navigate to simple route using its namehighway // Navigate to route with parametershighway // Navigate using urlhighway
The go
method can either take a string to navigate to a simple route using its name.
Or, an object with at least a name
key.
It can also take a params
object to pass dynamic parameters to the route.
The params
can also be an Array
which will be mapped onto the dynamic parts of the path in sequential order.
go
method
Options for the name {string}
The route nameparams {mixed}
AnObject
orArray
of dynamic parameters passed to the routepath {string}
To use instead of thename
andparams
to navigate directly to a known URL pathforce {boolean}
Force the route to execute even if it is the last executed route, defaultfalse
.
Can be useful when trying to navigate to the same page but with a different value for a dynamic parameter of the route
Backbone.Router specific options
These options are just passed to Backbone.Router.navigate
when executing the go
method.
trigger {boolean}
Trigger the route controller, defaulttrue
replace {boolean}
Replace the current entry in the browser history, defaultfalse
See the Backbone documentation for more info.
Catching client-side 404
You can declare a special route named 404
to catch inexisting routes
highway
before
and after
events / middlewares
Each route can trigger events using an event aggregator like Backbone.Events
or Backbone.Radio
// Listen to 'core:render' eventEvents // Declare a profile routehighway // Start the router passing the event aggregator instance in the `dispatcher` optionhighwaystart dispatcher: Events // Navigate to the routehighway
In this example, the route parameter name
will be passed to the event,
but it can be overridden by declaring specific params
for the event.
Dependencies
- Backbone >= 1.1.4
- Underscore >= 1.4.4
Demo / Example
Use npm to install dependencies and launch the demo server.
npm install && npm start
License
The MIT License (MIT)