Permalink
Browse files

Merge pull request #267 from marionettejs/wreqr

Adding Commands And Request/Response From Backbone.Wreqr
  • Loading branch information...
2 parents adb536d + 9e7817d commit 3e494fc7dd87135e7fde94765cdaebc032418f0f @derickbailey derickbailey committed Oct 4, 2012
View
@@ -20,6 +20,10 @@
* Application
* Application regions can now be specified as a jQuery selector string, a region type, or an object literal with a selector and type: `{selector: "#foo", regionType: MyCustomRegion}`
+ * added `.commands` as instance of Backbone.Wreqr.Commands, to facilitate command execution
+ * added `.execute` method for direct command execution
+ * added `.reqres` as instance of Backbone.Wreqr.RequestResponse, to facilitate request/response execution
+ * added `.request` method for direct requesting of a response
* triggerMethod
* Added `Marionette.triggerMethod` method to trigger an event and call the corresponding method. For example, `view.triggetMethod("before:render")` will trigger the "before:render" event and call the `onBeforeRender` method.
@@ -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,0 +1,20 @@
+describe("application commands", function(){
+
+ describe("when creating an instance of an Application", function(){
+ var App;
+
+ beforeEach(function(){
+ App = new Marionette.Application();
+ });
+
+ it("should provide command execution framework", function(){
+ expect(App.commands).toBeInstanceOf(Backbone.Wreqr.Commands);
+ });
+
+ it("should allow execution of commands directly", function(){
+ expect(typeof App.execute).toBe("function");
+ });
+
+ });
+
+});
@@ -0,0 +1,20 @@
+describe("application request/response", function(){
+
+ describe("when creating an instance of an Application", function(){
+ var App;
+
+ beforeEach(function(){
+ App = new Marionette.Application();
+ });
+
+ it("should provide request/response framework", function(){
+ expect(App.reqres).toBeInstanceOf(Backbone.Wreqr.RequestResponse);
+ });
+
+ it("should allow direct request", function(){
+ expect(typeof App.request).toBe("function");
+ });
+
+ });
+
+});
@@ -7,13 +7,25 @@
Marionette.Application = function(options){
this.initCallbacks = new Marionette.Callbacks();
this.vent = new Marionette.EventAggregator();
+ this.commands = new Backbone.Wreqr.Commands();
+ this.reqres = new Backbone.Wreqr.RequestResponse();
this.submodules = {};
var eventBinder = new Marionette.EventBinder();
_.extend(this, eventBinder, options);
};
_.extend(Marionette.Application.prototype, Backbone.Events, {
+ // Command execution, facilitated by Backbone.Wreqr.Commands
+ execute: function(){
+ this.commands.execute.apply(this.commands, arguments);
+ },
+
+ // Request/response, facilitated by Backbone.Wreqr.RequestResponse
+ request: function(){
+ return this.reqres.request.apply(this.reqres, arguments);
+ },
+
// Add an initializer that is either run at when the `start`
// method is called, or run immediately if added after `start`
// has already been called.

0 comments on commit 3e494fc

Please sign in to comment.