Adding a Centralized Event Dispatcher on Backbone.js
This article contains my solution to adding a simple global event dispatcher to Backbone. It should also help noobies (myself included) understand how Backbone events work (which has one big gotcha).
Sharing Events = Global Dispatcher
Today, I came across a fairly mundane – and probably common – problem: I have two views that need to talk to each other. An example for this would be when you have a status bar in one corner that gets updated when a user completes an action in another area. It turns out that Backbone (as far as I can tell) does not support this use case very well out of the box. Well, it does: it expects you to build that yourself.
Backbone supports a model where you publish and subscribe to things happening in your views/models (commonly known as an “event dispatcher“). For example, you can make your application do stuff when a user clicks on something or if a model attribute changes. The native solution localizes these events (probably a good thing) to the model/view that you’re working with. This works for simple stuff, but when you need it in other parts of your application, things break down. The short answer is that you need to build a global event dispatcher A.K.A. global event “hub.” Everything publishes (“trigger”) and listens (“bind”) to events from this object.
This is a common pattern. In fact, I found two solid articles on this topic. The first explains in detail why you need an event dispatcher. The second shows you how to make the dispatcher natively accessible by all of your Backbone classes.
Event Dispatcher Gotcha: Native Events
However, I felt both solutions weren’t quite there. The first forces you to pass around an Event object everywhere you need it. This is nice from a decoupling standpoint, but highly error prone. The second solution is nice, but makes the caller oblivious to the global event namespace they are triggering/binding to. This is dangerous because Backbone has native generic events that are fired when certain things happen. For example, when you edit a Model, it automatically fires a “change” event into its event dispatcher (which bubbles up to its Collection too). This means if that dispatcher was global, every object would see a “change” firing every time every Model changed. Not good.
Goals
I came up with my own solution that accomplishes three main goals:
- Retain native Backbone event triggering/binding
- Allow the developer to trigger/bind to global events
- Not require the developer to pass things around
Solution Code
(If you can’t read CoffeeScript, just use this converter to convert it back to JavaScript)
The following (very simple) code modifies your Backbone definition to attach the global dispatcher to all objects. The dispatcher is easily accessible from any Model, Route, View, or Collection through the global_dispatcher parameter. I thought about having it trigger events to the local dispatcher as well, but I decided that keeping them fully separate was in everybody’s best interest (to prevent events from accidentally colliding):
# centralized global_dispatcher object added to all Backbone Collection, Model, View, and Router classes(-> return if this.isExtended # attaching the Events object to the dispatcher variable dispatcher = _.extend({}, Backbone.Events, cid: "dispatcher") _.each [ Backbone.Collection::, Backbone.Model::, Backbone.View::, Backbone.Router:: ], (proto) -> # attaching a global dispatcher instance _.extend proto, global_dispatcher: dispatcher)()Example Code
The next section is a simple class I wrote that will demonstrate how these events work. I am defining a simple Collection and a Model. Note that I named the global and local events the SAME. This was to help demonstrate that the namespaces are in fact completely separate (as in, just because they are named the same doesn’t mean a local event will ever trigger a global event with the same name).
# See http://www.michikono.com/2012/01/11/adding-a-centralized-event-dispatcher-on-backbone-js/ for an explanation
class Test extends sBackbone.Model
initialize: () -> this.global_dispatcher.bind('model_custom_action', () -> console.log('GLOBAL TRIGGERED: test model custom action') ) this.bind('model_custom_action', () -> console.log('TRIGGERED: test model custom action') )
trigger_stuff: () -> console.log('triggering model') this.trigger('model_custom_action') this.global_dispatcher.trigger('model_custom_action')
class TestCollection extends sBackbone.Collection model: Test
initialize: () -> this.global_dispatcher.bind('collection_custom_action', () -> console.log('GLOBAL TRIGGERED: test collection custom action') ) this.bind('collection_custom_action', () -> console.log('TRIGGERED: test collection custom action') )
this.global_dispatcher.bind('model_custom_action', () -> console.log('GLOBAL TRIGGERED inside Collection: test model custom action') )
this.bind('model_custom_action', () -> console.log('TRIGGERED inside Collection: test model custom action') )
trigger_stuff: () -> console.log('triggering collection') this.trigger('collection_custom_action') this.global_dispatcher.trigger('collection_custom_action')
The following snippet illustrates triggering the events attached to the Collection. Note that we add a Model into this collection (which has no impact on the output). The trigger_stuff method triggers both a local and global event (in that order). The output shows that the events were picked up in the order fired (local, then global). Note that the Collection also listens to the “model_custom_action” event, which coincides with an event the Model triggers. This is very important.
# Trigger both the local and global event bindings for the collection
# Outputs:# triggering collection# TRIGGERED: test collection custom action# GLOBAL TRIGGERED: test collection custom action
collection = new TestCollection()# adding an empty, but fully valid Model instancecollection.add()collection.trigger_stuff()
The order of operations looks like this:
- Fire a local event
- The Collection picks it up
- END OF FIRST EVENT
- Fire global event
- The Collection’s globally attached event handler picks it up
- END OF SECOND EVENT
The next snippet shows what happens when you fire an event on a Model inside a Collection. It is also why I decided to keep things separate. This is a little hairy, so pay special attention.
# Trigger both the local and global event bindings for the model
# Outputs:# triggering model# TRIGGERED: test model custom action# TRIGGERED inside Collection: test model custom action# GLOBAL TRIGGERED inside Collection: test model custom action# GLOBAL TRIGGERED: test model custom action
collection = new TestCollection()# adding an empty, but fully valid Model instancecollection.add()# getting the just-added instanceinstance = collection.at(0)# trigger an event on the Modelinstance.trigger_stuff()
The order of operations looks like this:
- Fire a local event
- The Model picks it up
- The Collection picks it up since all events in children bubble up
- END OF FIRST EVENT
- Fire global event
- The Collection’s globally attached event handler picks it up
- The Model’s globally attached event handler picks it up
- END OF SECOND EVENT
Notice that in step #6, the Collection’s binding fires BEFORE the Model’s. This is key.
Step #3 fires because there is a LOCAL binding to the “model_custom_action” event in the Collection. The local binding is reacting to an event triggered in the child Model’s local event dispatcher. In other words, any event triggered from the local event dispatcher in a Model will bubble up to the Collection’s local event dispatcher and be otherwise indistinguishable from events triggered directly from that Collection.
Step #6, however, is different. That event did NOT originate from the child model’s local event dispatcher. Instead, it is reacting to the global bindings, which happen to share the same name as the event we saw earlier in step #3. Because it didn’t bubble up, the events are being processed in the order they were bound (via the bind() function). The Collection was defined before the Model, thus, the Collection’s global binding fires first.
In this last snippet, we demonstrate how Models behave when not inside a Collection.
# Trigger event bindings for a model not in a collection
# Outputs:# triggering model# TRIGGERED: test model custom action# GLOBAL TRIGGERED: test model custom action
instance = new Testinstance.trigger_stuff()
- Fire a local event
- The Model picks it up
- END OF FIRST EVENT
- Fire global event
- The Model’s globally attached event handler picks it up
- END OF SECOND EVENT
This is very straight forward if you managed to follow the last example. To get additional clarity, you may want to try renaming the events in the above class and re-run the examples.
By having the global dispatcher separate, you can consciously decide when an event should be “public,” as well as not clobber any existing Backbone functionality. Backbone is still really young (pre 1.0!), so I wanted to avoid using any solution that might break if they changed the internals. Also, completely preserving the behavior of event bubbling for Model-Collections is important to future proof my hack.
I hope this is useful for all of your Google-visitors!
