The CXAObservable service

Abstract

Overview of the CXAObservable service and the methods it supports.

The CXAObservable service provides the necessary support required for renderings to communicate and still remain loosely coupled, independent and unaware of other renderings in use. The basic concept is similar to the Observer design pattern except that it is not an Observable object that changes state but individual renderings that can trigger an event through the Observable, which other renderings are listening for. A rendering subscribes to events and when the event is emitted by another rendering, the subscriber is notified of the event through CXAObservable.

Internally, the CXAObservable service uses an implementation of CustomObservable to subscribe and emit using an instance of the observable. To support more complicated scenarios, you can swap out this implementation with other implementations such as RxJs Subject.

Communication between the renderings is managed during rendering initialization. For example, if any event is emitted before all the renderings are initialized (CXAApplication.IsInitialized = false), which could happen if a rendering emits an event during initialization, the event is held in the queue until all renderings have been initialized. The events in the queue are emitted in sequence. This helps prevent a missed event by the subscribers such as renderings that subscribe to an event after another rendering has emitted the event.

Sequence diagram illustrating the calls that occur

The CXAObservable service performs the following methods. It interacts with CXACartContext and uses various shared events.

Method

Description

Code

Subscribe to an event

A rendering subscribes to the event to perform a method. The message parameter used depends on what is passed in when the emitEvent function is called.

The listener is called with the event argument. It handles the argument based on the type of object emitted for the event.

This method returns the subscriber.

CXAObservable.subscribeToEvent(CXAEvent.SendMessage,
function (message) {

// Do something with the message

console.log(message);

});

where:

CXAEvent.SendMessage is the event name

function (message) is the listener

Emit an event

Rendering emits an event, which can be a string or any type of object. Best practice is to have a consistent type for each event that can be handled by all listeners.

CXAObservable.emitEvent(CXAEvent.SendMessage, "This parameter can be a string"); CXAObservable.emitEvent(CXAEvent.SendMessage, { message: "This parameter can be any object" });

Subscribe to a product

Rendering subscribes to all events associated with a specific product ID in order to perform a method.

The listener is called with two arguments:

  • The event name

  • The event argument

Returns the subscriber.

CXAObservable.subcribeToProduct(productid,ProductEventHandler);

where:

ProductEventHandler is the listener.

Subscribe to a product event

Rendering subscribes to the event associated with the specific product ID to perform a method. The listener is called with the event argument.


CXAObservable.subcribeToProduct(productId, ProductEventHandler);

where:

ProductEventHandler is the listener.

Unsubscribe from an event

Rendering unsubscribes from an event.

CXAObservable.unsubscribeFromEvent(subscriber);

where:

subscriber is the object returned when subscribeToEvent/subscribeToProduct/subscribeToProductEvent is called.

SXA Storefront uses the following shared events.

Event

Description

Methods

CXAEvent.ClearMessage

Requests the Message Summary rendering to remove displayed messages.

Listening

  • Message Summary

Emitting

  • Add to Cart

  • Checkout Billing

  • Checkout Review

  • Cart Lines

  • Product Bundle

  • Product Variant

CXAEvent.SendMessage

Requests the Message Summary rendering to display the message.

Event argument:

{
  type:
CXAMessageType,
  message: String
}

CXAMessageType enum:

  • Info

  • Error

  • Warning

Listening

  • Message Summary

Emitting

  • Product Bundle

  • Product Inventory

  • Product Variant

CXAEvent.CartUpdated

Emits the event when the latest cart is received. This event is emitted by the CXACartContext whenever the object received by the context is of type CartJsonResult.

Listening

  • Free Gift Selections

  • Cart Lines

  • Minicart

  • Cart Promotion

  • Cart Total

Emitting

  • Free Gift Selection

  • Cart Lines

  • Minicart

  • CXACartContext

CXAEvent.SetPrice

Requests the Product Price rendering to display the price of the current product variant or product bundle selection.

Event argument:

{
  productId: String,
  listPrice: Number,
  adjustedPrice:
Number,
  isOnSale: Boolean,
  savingsMessage:
String
}

Listening

  • Product Price

Emitting

  • Product Bundle

  • Product Variant

CXAEvent.SelectedProduct

Emits an event when a product variant is selected.

Event argument:
{
  CurrentCatalogName:
String,
  CurrentProductId:
String,
  CurrentVariantId:
String
}

Listening

  • Add to Cart

  • Product Inventory

Emitting

  • Product Variant

CXAEvent.SelectedBundleProduct

Emits an event when a product bundle is selected.

Event argument:

{
  bundleSelection:
BundleSelection
}

Listening

  • Add to Cart

  • Product Inventory

Emitting

  • Product Bundle

CXAEvent.SelectedProductValid

Emits the event to indicate that the current product selection is valid so that the Add to Cart rendering can enable the Add to Cart button.

Listening

  • Add to Cart

Emitting

  • Product Bundle

  • Product Inventory

  • Product Variant

CXAEvent.SelectedProductInvalid

Emits the event to indicate that the current product selection is valid so that the Add to Cart rendering can disable the Add to Cart button.

Listening

  • Add to Cart

Emitting

  • Product Bundle

  • Product Inventory

  • Product Variant

CXAEvent.BundleStockStatusValid

Emits the event to indicate that the current bundle selection’s stock status is valid so that the Product Bundle can then request for the Bundle Selection’s price.

Event argument:

{
  productId: String
}

Listening

  • Product Bundle

Emitting

  • Product Inventory

CXAEvent.GetStockInfo

Product Inventory rendering emits this event when the response is received from the API endpoint Catalog/GetCurrentProductStockInfo.

Event argument:

{
  productId: String,
  stockInfos: Array
}

Listening

  • Product Bundle

Emitting

  • Product Inventory

CXAEvent.DiscountApplied

The CXACartContext service emits the event after calling to the API endpoint Cart/ApplyDiscount.

Listening

  • Cart Lines

  • Cart Promotion

  • Cart Total

Emitting

  • CXACartContext

CXAEvent.DiscountRemoved

The CXACartContext service emits the event after calling to the API endpoint Cart/RemoveDiscount.

Listening

  • Cart Lines

  • Cart Promotion

  • Cart Total

Emitting

  • CXACartContext