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, Oracle Commerce Cloud Service 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;

});