Listen for messages from a particular object instance
The PubSub
library provides a way for code to publish and
subscribe to a set of “global” messages.
Any code in the application can publish messages to a topic and any code can
listen for those messages. There may be a need, however, to listen for messages coming only
from a specific instance of an object. To manage this use case, Commerce includes the event-dispatcher
module. Any object created from a module
that extends event-dispatcher
can trigger events and allow other objects to
register as listeners for those events.
The event-dispatcher
module provides two functions, trigger()
and on()
, that facilitate event triggering and event listening, respectively. In the example below, the ExampleDialog
view model extends event-dispatcher
and defines two events that can be fired, save-event
and cancel-event
. To trigger the events, the view associated with ExampleDialog
could call the trigger()
functions as needed, for example, when the Save or Cancel button is clicked.
/** * ExampleDialog.js */
define (["shared/ccLibs/event-dispatcher"], function(EventDispatcher) { "use strict";
/**
* Example of a module that extends EventDispatcher, enabling instances of the
* class to fire events to any listeners/event handlers registered.
* @see EventDispatcher
*/
function ExampleDialog() {
// Invoke superclass constructor to inherit any instance properties.
EventDispatcher.call(this);
this.p1 = "property 1 value";
this.p2 = "property 2 value";
}
// Extend EventDispatcher so we can dispatch events.
ExampleDialog.prototype = Object.create(EventDispatcher.prototype);
ExampleDialog.prototype.constructor = ExampleDialog;
// Define constants for any events we want to fire. These need only be unique
// within this module because corresponding listeners receive events from a
// given instance of this module.
ExampleDialog.SAVE = "save-event";
ExampleDialog.CANCEL = "cancel-event";
/**
* Corresponding view could be set up to call this method when the
* dialog's Save button is clicked, for example.
*/
ExampleDialog.prototype.save = function() {
// Fire SAVE event. Any additional arguments (beyond the first) are
// passed along to the event handler/listener.
this.trigger(ExampleDialog.SAVE, this.p1);
};
/**
* Corresponding view could be set up to call this method when the
* dialog's cancel button is clicked, for example.
*/
ExampleDialog.prototype.cancel = function() {
// Fire CANCEL event.
this.trigger(ExampleDialog.CANCEL);
};
/**
* Displays the dialog.
*/
ExampleDialog.prototype.show = function() {
// Do something to display the dialog. Perhaps trigger an event as well.
};
return ExampleDialog;
});
This code sample creates an instance of ExampleDialog
and provides
listeners, using the on()
function, for the save and cancel events
triggered in that instance.
/**
* Example.js
*/
define (["path/to/ExampleDialog"], function(ExampleDialog) {
"use strict";
/**
* Example of a module that listens for ExampleDialog events. Does nothing
* real or useful other than establishing how to add listeners to an
* EventDispatcher.
* @see ExampleDialog */
function Example() {
// Note: The code in this constructor might more typically be in an
// initialize method or somewhere else.
var dialog = new ExampleDialog();
// Add listeners for save and cancel events. 3rd arg, if provided, sets the
// context for the listener
dialog.on(ExampleDialog.SAVE, this.onSave, this);
dialog.on(ExampleDialog.CANCEL, this.onCancel);
dialog.show();
}
/**
* Listener/handler for dialog save events.
* @param args {Array} Any args passed along when event is fired.
*/
Example.prototype.onSave = function(args) {
// Do something...
console.log(args[0]);
};
/**
* Listener/handler for dialog cancel events.
* @param args {Array} Any args passed along when event is fired.
*/
Example.prototype.onCancel = function(args) {
// Do something else...
if (args.length === 0) {
console.log("No args passed with cancel event.");
}
};
return Example;
});