Merge pull request tbranyen#59 from liamks/master

Added documentation for app wide events

app/templates/example.html

@@ -32,6 +32,7 @@ <h1>Contents</h1>
         <li><a data-bypass href="#namespace">Setting your namespace</a>
         <li><a data-bypass href="#modules">Creating a module</a>
         <li><a data-bypass href="#templates">Working with templates</a>
+        <li><a data-bypass href="#events">Working with Application Wide Events</a>
         <li><a data-bypass href="#plugins">Working with libraries and plugins</a>
       </ul>
     <li><a data-bypass href="#custom-build">Using the build tool</a>
@@ -265,6 +266,41 @@ <h3 id="templates">Working with templates</h3>
   </code></pre>
   </p>
 
+  <h3 id="events">Working with Application Wide Events</h3>
+  <p>Application wide events provide a convenient way for modules to communicate with each other. <code>namespace.app</code> references a copy of the Backbone.Events object. <a href="http://documentcloud.github.com/backbone/#Events">More information on Backbone Events</a></p>
+
+  <p>
+  To bind a callback function to an event:
+
+  <pre><code>
+  //binding an annonymous function to the event "all" with a context of <code>this</code>.
+  namespace.app.on("all", function(){...}, this);
+  </code></pre>
+  </p>
+
+  <p>
+  To remove a callback function (or many) from an event:
+
+  <pre><code>
+  // Removes just the doSomething callback.
+  namespace.app.off("change", doSomething);
+
+  // Removes all "change" events.
+  namespace.app.off("change");
+
+  // Removes all events from the namespace.app object. 
+  namespace.app.off(); 
+  </code></pre>
+  </p>
+
+  <p>
+  To trigger the "change" event:
+
+  <pre><code>
+  namespace.app.trigger("change", [*args]);
+  </code></pre>
+  </p>
+
   <h3 id="plugins">Working with libraries and plugins</h3>
   <p>Libraries and plugins are easily added to the application, by placing them inside the <code>assets/js/libs/</code> directory.
   If you have many plugins in your application, it may make sense to create a separate folder such as <code>assets/js/plugins/</code> 

readme.md

@@ -132,6 +132,16 @@ MyModule.Model = Backbone.Model.extend({ /* ... */ });
 MyModule.Router = Backbone.Router.extend({ /* ... */ });
 ```
 
+## Events ##
+
+Application wide events provide a convenient way for modules to communicate with each other. `namespace.app` references a copy of the Backbone.Events object, providing access to `.on()`, `.off()`, and `.trigger()`, that are documented in [Backbone.js Events](http://documentcloud.github.com/backbone/#Events)
+
+For example, to add a callback to the "all" event:
+
+```javascript
+namespace.app.on("all", function(){}, this);
+```
+
 ## HTML5 History and Hash Based Navigation ##
 
 Out the box Backbone Boilerplate enables `pushState`.  It also supplies a script