Permalink
Browse files

docs for commands, request/response, and re-adding event aggregator docs

  • Loading branch information...
1 parent 4ecc80b commit 9e7817d7e1acfac7cc3c3d1d70c23fe663743c70 @derickbailey derickbailey committed Oct 3, 2012
Showing with 153 additions and 3 deletions.
  1. +45 −0 docs/marionette.commands.md
  2. +59 −3 docs/marionette.eventaggregator.md
  3. +45 −0 docs/marionette.requestresponse.md
  4. +4 −0 readme.md
@@ -0,0 +1,45 @@
+# Marionette.commands
+
+An application level command execution system. This allows components in
+an application to state that some work needs to be done, but without having
+to be explicitly coupled to the component that is performing the work.
+
+No response is allowed from the execution of a command. It's a "fire-and-forget"
+scenario.
+
+Facilitated by [Backbone.Wreqr](https://github.com/marionettejs/backbone.wreqr)'s
+Commands object.
+
+## Register A Command
+
+To register a command, call `App.commands.register` and provide a name for
+the command to handle, and a callback method.
+
+```js
+var App = new Marionette.Application();
+
+App.commands.register("foo", function(bar){
+ console.log(bar);
+});
+```
+
+## Execute A Command
+
+To execute a command, either call `App.commands.execute` or the more direct
+route of `App.execute`, providing the name of the command to execute and
+any parameters the command needs:
+
+```js
+App.execute("foo", "baz");
+// outputs "baz" to the console, from command registered above
+```
+
+## Remove / Replace Commands
+
+To remove a command, call `App.commands.removeHandler` and provide the
+name of the command to remove.
+
+To remove all commands, call `App.commands.removeAllHandlers()`.
+
+To replace a command, simply register a new handler for an existing
+command name. There can be only one command handler for a given command name.
@@ -4,7 +4,63 @@ An event aggregator is an application level pub/sub mechanism that allows variou
pieces of an otherwise segmented and disconnected system to communicate with
each other.
-## Marionette.EventAggregator Has Moved
+Facilitated by [Backbone.Wreqr](https://github.com/marionettejs/backbone.wreqr)'s
+EventAggregator object.
-It's new home is with the [Backbone.Wreqr](https://github.com/marionettejs/backbone.wreqr)
-plugin. Please see that repository for downloads and documentation.
+## Basic Usage
+
+Backbone.Marionette provides an event aggregator with each application instance:
+`MyApp.vent`. You can also instantiate your own event aggregator:
+
+```js
+myVent = new Backbone.Marionette.EventAggregator();
+```
+
+Passing an object literal of options to the constructor function will extend the
+event aggregator with those options:
+
+```js
+myVent = new Backbone.Marionette.EventAggregator({foo: "bar"});
+myVent.foo // => "bar"
+```
+
+## BindTo
+
+The `EventAggregator` extends from the [`EventBinder`](./marionette.eventbinder.md) object to easily track
+and unbind all event callbacks, including inline callback functions.
+
+The `bindTo` method, though, has been proxied to only take 3 arguments. It assumes
+that the object being bound to is the event aggregator directly, and does not allow
+the bound object to be specified:
+
+```js
+vent = new Backbone.Marionette.EventAggregator();
+
+vent.bindTo("foo", function(){
+ alert("bar");
+});
+
+vent.unbindAll();
+
+vent.trigger("foo"); // => nothing. all events have been unbound.
+```
+
+## Decoupling With An Event-Driven Architecture
+
+You can use an event aggregator to communicate between various modules of your
+application, ensuring correct decoupling while also facilitating functionality
+that needs more than one of your application's modules.
+
+```js
+var vent = new Backbone.Marionette.EventAggregator();
+
+vent.bind("some:event", function(){
+ alert("Some event was fired!!!!");
+});
+
+vent.trigger("some:event");
+```
+
+For a more detailed discussion and example of using an event aggregator with
+Backbone applications, see the blog post: [References, Routing, and The Event
+Aggregator: Coordinating Views In Backbone.js](http://lostechies.com/derickbailey/2011/07/19/references-routing-and-the-event-aggregator-coordinating-views-in-backbone-js/).
@@ -0,0 +1,45 @@
+# Marionette.RequestResponse
+
+An application level request/response system. This allows components in
+an application to request some information or work be done by another
+part of the app, but without having to be explicitly coupled to the
+component that is performing the work.
+
+A return response is expected when making a request.
+
+Facilitated by [Backbone.Wreqr](https://github.com/marionettejs/backbone.wreqr)'s
+RequestResponse object.
+
+## Register A Request Handler
+
+To register a command, call `App.reqres.register` and provide a name for
+the command to handle, and a callback method.
+
+```js
+var App = new Marionette.Application();
+
+App.reqres.register("foo", function(bar){
+ return bar + "-quux";
+});
+```
+
+## Request A Response
+
+To execute a command, either call `App.reqres.request` or the more direct
+route of `App.request`, providing the name of the command to execute and
+any parameters the command needs:
+
+```js
+App.request("foo", "baz"); // => returns "baz-quux"
+```
+
+## Remove / Replace A Request Handler
+
+To remove a request handler, call `App.reqres.removeHandler` and provide the
+name of the request handler to remove.
+
+To remove all request handlers, call `App.reqres.removeAllHandlers()`.
+
+To replace a request handler, simply register a new handler for an existing
+request handler name. There can be only one request handler
+for a given request name.
View
@@ -131,6 +131,8 @@ These are the strings that you can pull to make your puppet dance:
* [**Backbone.Marionette.Region**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.region.md): Manage visual regions of your application, including display and removal of content
* [**Backbone.Marionette.Layout**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.layout.md): A view that renders a layout and creates region managers to manage areas within it
* [**Backbone.Marionette.EventAggregator**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.eventaggregator.md): An extension of Backbone.Events, to be used as an event-driven or pub-sub tool
+* [**Backbone.Marionette.Commands**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.commands.md): An extension of Backbone.Wreqr.Commands, a simple command execution framework
+* [**Backbone.Marionette.RequestResponse**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.requestresponse.md): An extension of Backbone.Wreqr.RequestResponse, a simple request/response framework
* [**Backbone.Marionette.Renderer**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.renderer.md): Render templates with or without data, in a consistent and common manner
* [**Backbone.Marionette.TemplateCache**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.templatecache.md): Cache templates that are stored in `<script>` blocks, for faster subsequent access
* [**Backbone.Marionette.Callbacks**](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.callbacks.md): Manage a collection of callback methods, and execute them as needed
@@ -139,6 +141,8 @@ The following have been extracted in to separate plugins:
* [**Backbone.EventBinder**](https://github.com/marionettejs/backbone.eventbinder): An event binding manager, to facilitate binding and unbinding of events
* [**Backbone.Wreqr.EventAggregator**](https://github.com/marionettejs/backbone.wreqr): An event aggregator, to facilitate pub/sub and event architecture. Part of a suite of messaging based patterns
+* [**Backbone.Wreqr.Commands**](https://github.com/marionettejs/backbone.wreqr): A simple command execution system
+* [**Backbone.Wreqr.RequestResponse**](https://github.com/marionettejs/backbone.wreqr): A simple request/response system
Please note that this is documentation is rather dry - it's meant to be a reference for
those that just need a reference. If you're looking for an introduction and/or

0 comments on commit 9e7817d

Please sign in to comment.