backbone.eventrouter

Backbone.EventRouter
====================

   

About Backbone.EventRouter

Backbone.EventRouter extends the Backbone.Router. It is coupled with a Backbone.Radio Channel such that when an event is triggered on the channel, it will set the route URL, or when a URL matches a route it will throw an event on the channel.

This router was built from scripts open sourced from RoundingWell.com.

Why yet another Backbone router?

Early on we attempted to adopt event based routing but found that the patterns led to a lot of repetition. Not only did you need to define your routes in the router, you also had to do it in corresponding events. This router helps prevent the repetition and makes the concept maintainable. This extension allows you to use Backbone's router how it was intended ({trigger: false}), as well as allowing you to change the state of your app fully through events, using the router to merely kick-off the initial state.

##### But Ember does it differently...
Quite a good argument against Backbone's router is that it isn't Ember's router, and you'll find many Backbone.Router extensions modeling functionality from that router. While that is a very valid use case, we find Ember's router to be very heavy. That router often has the concern of handling the routes, fetching the data and kicking off an app (aka: sub-app, module, component, widget, etc).

##### Backbone.EventRouter is simplistic
This router is much simpler in that it listens for routes and triggers events, and listens for events and replace the URL with the applicable route. That's essentially it. You're on your own as far as how to handle those events. But we'd recommend something like marionette.toolkit.routerapp.

Documentation Index

* EventRouter's channelName
* EventRouter's routeTriggers
* EventRouter Events
* "before:route" event
* ["before:route:[name]" event](#beforeroutename-event)
* "noMatch" event
* EventRouter API
* getChannel
* addRouteTrigger
* getDefaultRoute
* navigateFromEvent
* translateRoute

EventRouter's channelName

Default Value: 'event-router'

Specify a channelName in your router class definition. This should be a
string or a function returning a string that indicates the Backbone.Radio
Channel name
that EventRouter will use.

``js
Backbone.EventRouter.extend({
channelName: 'my-event-channel'
});
`

Alternatively, you can specify a channelName in the options for
the constructor:

`js
var MyEventRouter = Backbone.EventRouter.extend({...});

new MyEventRouter({
channelName: 'my-event-channel'
});
`

EventRouter's routeTriggers


routeTriggers can be a hash or function on the definition
or passed as an option when instantiating an EventRouter.

This hash is used to add multiple trigger routes at instantiation.
Essentially addRouteTrigger is called for each route trigger.
More information about route triggers can be found here.

`js
new MyEventRouter({
routeTriggers: {
'some:event': 'some/url',
'thing:list': 'other/:param',
'thing:item': ['some/thing/:id', 'some/thing']
}
});

`

EventRouter Events

These are events triggered on the EventRouter itself. They are not triggered on the Radio channel. The Radio channel should be used strictly for routing events.

$3

The "before:route" event is functionally equivalent to Backbone's "route" event but triggered immediately before the route handler instead of after. See Backbone.Router.route for more information.

$3

The "before:route:[name]" event is functionally equivalent to Backbone's "route:[name]" event but triggered immediately before the route handler instead of after. See Backbone.Router.route for more information.

$3

If any event triggered on the Radio Channel is not handled by this EventRouter, this event will be triggered and receive the event string and any data sent to the event.

`js
var myEventRouter = new MyEventRouter({
routeTriggers: {
'some:event': 'some/url',
'thing:list': 'other/:param'
}
});

myEventRouter.on('noMatch', function(event, data){
console.log('The event ' + event + ' with data ' + data + ' was not handled by this router!');
});

var routeChannel = myEventRouter.getChannel();

// "The event event:not:handled with data foo was not handled by this router!" will be logged
routeChannel.trigger('event:not:handled', 'foo');
`




EventRouter API

$3

Gets the EventRouter's Backbone.Radio Channel instance.

`js
var router = new Backbone.EventRouter({
channelName: 'my-event-channel'
});

var routerChannel = router.getChannel();

routerChannel.on('foo', function(){
console.log('Same channel!');
});

// Triggering here will log: "Same channel!"
Backbone.Radio.trigger('my-event-channel', 'foo');
`




$3

Adds a routerTrigger, and route(s) to Backbone.Router
which, on route, triggers the appropriate event.

Conversely when the event is triggered, the URL will update
to match the route paired with the event.

`js
myEventRouter.addRouteTrigger('some/url/:param', 'some:event');

var myRouterChannel = myEventRouter.getChannel();

myRouterChannel.on('some:event', function(param){
console.log('Triggered: ' + param);
});

// Will console log "Triggered foo"
myEventRouter.navigate('some/url/foo', { trigger: true });

`

This function also takes an array of routes. Any route in the array will
trigger the given event. In this case the first route in the array is
considered the default route and will be matched if the event is triggered.

`js
myEventRouter.addRouteTrigger(['some/url/:param', 'some/url', 'other/:section/:id'], 'some:event');

var myRouterChannel = myEventRouter.getChannel();

// Will route URL to "some/url/bar"
myRouterChannel.trigger('some:event', 'bar');
`

Note: Splat routes and Optional params are not currently supported. ( ie: "some/url(/:param)" )
Similar handling of multiple routes can be done by setting an array of possible permutations.
You can additionally handle these routes as your normally would on a Backbone.Router.

$3

Get the default route string.
It will be either the first of the array or the passed-in event if singular.

`js
var myEventRouter =new MyEventRouter({
routeTriggers: {
'some:event': ['some/url/:param', 'some/url', 'other/:section/:id'],
'thing:list': 'other/:param'
}
});

// will return 'some/url/:param'
myEventRouter.getDefaultRoute('some:event');

// will return 'other/:param'
myEventRouter.getDefaultRoute('thing:list');
`

$3

Takes an event string and any arguments passed to that event and translates
the event into a URL and navigates to it without re-triggering the route.

`js
var myEventRouter =new MyEventRouter({
routeTriggers: {
'some:event': ['some/url/:param', 'some/url', 'other/:section/:id'],
'thing:list': 'other/:param'
}
});

// Will change the route to "some/url/foo" but will not trigger the route or event
myEventRouter.navigateFromEvent('some:event', 'foo');
`

$3

Takes a route string and an array of arguments
and returns a url with the named params replaced with the argument values.

`js
// will return 'some/url/foo/22'
myEventRouter.translateRoute('some/url/:param/:id', ['foo', 22]);
`

Getting Help

If you have questions or concerns please feel free to open an issue.
Additionally join us on the Marionette Gitter to have a chat.
Everyone there is happy to discuss design patterns.




Project Details

#### Library Downloads

You can download the latest builds directly from the dist folder above.

#### Available Packages

Via npm
`
$ npm install backbone.eventrouter
`

Via bower
`
$ bower install backbone.eventrouter
`


Currently Backbone.EventRouter is available via npm and bower. If you would like add it to another channel, please
open an issue.

#### Changelog

For change logs and release notes, see the changelog file.

#### Compatibility and Requirements

Backbone.EventRouter currently requires Backbone 1.1.1+`.

Backbone.EventRouter supports IE8+ and modern browsers.

How to Contribute

If you would like to contribute to Backbone.EventRouter's source code, please read
the guidelines for pull requests and contributions.
Following these guidelines will help make your contributions easier to
bring into the next release.

$3

Report issues with Backbone.EventRouter, and submit pull requests to fix problems or to
create summarized and documented feature requests (preferably with the feature implemented in the pull request).

===

This library is © 2015 RoundingWell. Distributed under MIT license.