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;
});