The PubSub library provides a way for code to publish and subscribe to a set of “global” messages. That is, 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 Cloud 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; });