Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Adding examples

  • Loading branch information...
commit 180d2b4eea0ae7323393f66ac994166710c47ad1 1 parent 64a58eb
Eric Feminella authored

Showing 1 changed file with 156 additions and 0 deletions. Show diff stats Hide diff stats

  1. +156 0 README.md
156 README.md
Source Rendered
... ... @@ -0,0 +1,156 @@
  1 +##EventBroker API##
  2 +Provides a general purpose Event Broker implementation to Backbone based on the Backbone Events API. The EventBroker can be used directly to serve as a centralized event management mechanism for an entire application. Additional, context specific, namespaced brokers can also be created in order to provide unique brokers within a particular part of an application.
  3 +
  4 +###Basic Usage###
  5 +The `EventBroker` can be used directly to publish and subscribe to events of interest:
  6 +``` javascript
  7 +var Users = Backbone.Collection.extend{{
  8 + broker: Backbone.EventBroker,
  9 + initialize: function(){
  10 + this.broker.on('users:add', this.add, this);
  11 + },
  12 + add: function(user) {
  13 + console.log(user.id);
  14 + }
  15 +};
  16 +
  17 +var UserEditor = Backbone.View.extend({
  18 + el: '#editor',
  19 + broker: Backbone.EventBroker,
  20 + initialize: function(broker){
  21 + this.$userId = this.$('#userId');
  22 + },
  23 + add: function() {
  24 + // publish an event
  25 + var user = new User({id: this.$userId().val()});
  26 + this.broker.trigger('user:add', user);
  27 + }
  28 +};
  29 +// ...
  30 +
  31 +```
  32 +
  33 +###Creating namespaced EventBrokers###
  34 +The `EventBroker` API can be used to create and retrieve any number of specific namespaced `EventBrokers`. A namespaced `EventBroker` ensures that all events are published and subscribed against a specific namespace.
  35 +
  36 +Namespaced `EventBrokers` are retrieved via `Backbone.EventBroker.get(<i>namespace</i>)`. If an `EventBroker` has not been created for the given namespace, it will be created and returned. All subsequent retrievals will return the same `EventBroker` instance for the specified namespace; i.e. only one unique `EventBroker` is created per namespace.
  37 +
  38 +``` javascript
  39 +var Users = Backbone.Collection.extend{{
  40 + // use the 'users' broker
  41 + userBroker: Backbone.EventBroker.get('users'),
  42 + initialize: function(broker){
  43 + this.userBroker.on('add', this.add, this);
  44 + },
  45 + add: function(user) {
  46 + console.log(user.id);
  47 + }
  48 +};
  49 +
  50 +var UserEditor = Backbone.View.extend({
  51 + el: '#editor',
  52 + // use the 'users' broker
  53 + usersBroker: Backbone.EventBroker.get('users'),
  54 + // also use the 'roles' broker
  55 + rolesBroker : Backbone.EventBroker.get('roles'),
  56 + initialize: function(broker){
  57 + this.$userId = this.$('#userId');
  58 + },
  59 + add: function() {
  60 + // publish an event
  61 + var user = new User({id: this.$userId().val()});
  62 + this.usersBroker.trigger('add', user);
  63 + }
  64 +};
  65 +
  66 +```
  67 +
  68 +Since namespaced `EventBrokers` ensure events are only piped thru the `EventBroker` of the given namespace, it is not necessary to prefix event names with the specific namespace to which they belong. While this can simplify implementation code, you can still prefix event names to aid in readability if desired.
  69 +
  70 +``` javascript
  71 +var Users = Backbone.Collection.extend{{
  72 + // use the 'users' broker
  73 + userBroker: Backbone.EventBroker.get('users'),
  74 + initialize: function(broker){
  75 + // prefix the namespace if desired
  76 + this.userBroker.on('users:add', this.add, this);
  77 + },
  78 + add: function(user) {
  79 + console.log(user.id);
  80 + }
  81 +};
  82 +
  83 +var UserEditor = Backbone.View.extend({
  84 + el: '#editor',
  85 + // use the 'users' broker
  86 + usersBroker: Backbone.EventBroker.get('users'),
  87 + // also use the unique 'roles' broker
  88 + rolesBroker: Backbone.EventBroker.get('roles'),
  89 + initialize: function(broker){
  90 + this.$userId = this.$('#userId');
  91 + },
  92 + add: function() {
  93 + // publish an event
  94 + var user = new User({id: this.$userId().val()});
  95 + // prefix the namespace if desired
  96 + this.usersBroker.trigger('users:add', user);
  97 + }
  98 +};
  99 +
  100 +```
  101 +
  102 +###Registering Interests###
  103 +Modules can register events of interest with an `EventBroker` via the default 'on' method or the `register` method. The `register` method allows for registering multiple event/callback mappings for a given context in a manner similar to that of the [events hash](http://documentcloud.github.com/backbone/#View-extend "Title") in a Backbone.View.
  104 +
  105 +``` javascript
  106 +// Register event/callbacks based on a hash and associated context
  107 +var Users = Backbone.Collection.extend(
  108 +{
  109 + broker: Backbone.EventBroker,
  110 +
  111 + initialize: function()
  112 + {
  113 + this.broker.register({
  114 + 'user:select' : 'select',
  115 + 'user:deselect' : 'deselect',
  116 + 'user:edit' : 'edit',
  117 + 'user:update' : 'update',
  118 + 'user:remove' : 'remove'
  119 + }, this );
  120 + },
  121 + select: function() { ... },
  122 + deselect: function() { ... },
  123 + edit: function() { ... },
  124 + update: function() { ... },
  125 + remove: function() { ... }å
  126 +});
  127 +
  128 +```
  129 +
  130 +Alternately, Modules can simply define an "interests" property containing particular event/callback mappings of interests and register themselves with an `EventBroker`
  131 +
  132 +``` javascript
  133 +// Register event/callbacks based on a hash and associated context
  134 +var Users = Backbone.Collection.extend(
  135 +{
  136 + // defines events of interest and their corresponding callbacks
  137 + this.interests: {
  138 + 'user:select' : 'select',
  139 + 'user:deselect' : 'deselect',
  140 + 'user:edit' : 'edit',
  141 + 'user:update' : 'update',
  142 + 'user:remove' : 'remove'
  143 + },
  144 + initialize: function()
  145 + {
  146 + // register this object with the EventBroker
  147 + Backbone.EventBroker.register( this );
  148 + },
  149 + select: function() { ... },
  150 + deselect: function() { ... },
  151 + edit: function() { ... },
  152 + update: function() { ... },
  153 + remove: function() { ... }
  154 +});
  155 +
  156 +```

0 comments on commit 180d2b4

Please sign in to comment.
Something went wrong with that request. Please try again.