Publishing and retrieving information with Dojo events for widgets

If your custom widget must use data that is generated by a different widget or provide data that another widget needs, you can use a Dojo event to retrieve or provide the data. To use data that is generated by a widget, you can subscribe to the Dojo event that the other widget publishes. To have a widget provide information that another widget can use, you can use a Dojo event to publish this information. The other widgets can subscribe to the Dojo event that you published.

Retrieving information from other widgets with Dojo events

If a widget publishes a Dojo event that contains any required data for your widget, you can have your custom widget subscribe to the Dojo event to retrieve the data. Use the dojo.topic.subscribe API to subscribe to published widget events. To subscribe to a published Dojo event, the following code must be included within the top-level JSP file for the widget that needs to subscribe to the Dojo event:

dojo.topic.subscribe('identifier_eventAction', location.function);

Where

identifier: The widget that generates the data within the published event.
eventAction: The event that is being subscribed to. For example, if information in another widget is changed or completed.
location: The file that is subscribed to which includes the code to publish the event.
function: The function to call in your custom widget when the information from the published event is retrieved.

For example, on the Product Details page, the Full Image widget subscribes to the following Dojo events that are published by the Defining Attributes widget:

DefiningAttributes_Changed: Published when the value for an attribute is selected while other attributes still do not have values selected and the SKU is not resolved. For example, when a shopper selects the size for a product, but not the value for the product color yet.
DefiningAttributes_Resolved: Published when the value for an attribute is selected and all other attributes have values and the SKU is resolved.

These events are used by the Full Image widget to determine the correct product image to display when the attribute values are selected by shoppers. The Full Image widget subscribes to these events with the following code:

			dojo.topic.subscribe('DefiningAttributes_Resolved', productDisplayJS.updateProductImage);
			dojo.topic.subscribe('DefiningAttributes_Changed', productDisplayJS.updateProductImage);

The publishing of these events and more events for widgets that display on the Product Detail page are defined in the Stores\WebContent\widgetdir\Common\CatalogEntry\javascript\ProductDisplay.js file.

The following table identifies the Dojo events that are published by default. You can have a widget subscribe to the events to retrieve data for the widget to use.

Dojo events that are published by default.
Dojo event	Description (event trigger)	Published parameters	File that publishes the event
`ShopperActions_Changed`	This event publishes a notification that there is a change in quantity to a product that a shopper is viewing.	This event publishes the new quantity of the item after a shopper changes the quantity.	`WC_eardir`/Stores.war/`widgetdir`/Common/CatalogEntry/javascript/ProductDisplay.js `WC_eardir`\Stores.war\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js `workspace_dir`\Stores\WebContent\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js
`DefiningAttributes_Changed_productId`	This event occurs when a shopper changes the defining attributes of a catalog entry. This event also occurs after the shopper saves the changes. This event concatenates the product ID of the changed catalog entry to the event name. Subscribe to this event when your widget needs notification of the changes to products and specific catalog entries (SKUs).	The event publishes the catalog entry ID and product ID of the catalog entry that includes the defining attribute changes.	`WC_eardir`/Stores.war/`widgetdir`/Common/CatalogEntry/javascript/ProductDisplay.js `WC_eardir`\Stores.war\WebContent\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js `workspace_dir`\Stores\WebContent\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js
`DefiningAttributes_Changed`	This event occurs when a shopper changes the defining attributes of a catalog entry. This event also occurs after the shopper saves the changes.	The event publishes the catalog entry ID and product ID of the catalog entry that includes the defining attribute changes.	`WC_eardir`/Stores.war/`widgetdir`/Common/CatalogEntry/javascript/ProductDisplay.js `WC_eardir`\Stores.war\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js `workspace_dir`\Stores\WebContent\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js
`DefiningAttributes_Resolved`	This event occurs when a shopper saves changes to the defining attributes of a catalog entry.	The event publishes the catalog entry ID and product ID of the catalog entry that includes the saved defining attribute changes.	`WC_eardir`/Stores.war/`widgetdir`/Common/CatalogEntry/javascript/ProductDisplay.js `WC_eardir`\Stores.war\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js `workspace_dir`\Stores\WebContent\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js
`DefiningAttributes_Resolved_productId`	This event occurs when a shopper saves changes to the defining attributes of a catalog entry within the shopping cart. This event concatenates the product ID of the changed catalog entry to the event name. Subscribe to this event when your widget needs notification of the changes to products and specific catalog entries (SKUs).	The event publishes the catalog entry ID and product ID of the catalog entry that includes the saved defining attribute changes.	`WC_eardir`/Stores.war/`widgetdir`/Common/CatalogEntry/javascript/ProductDisplay.js `WC_eardir`\Stores.war\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js `workspace_dir`\Stores\WebContent\`widgetdir`\Common\CatalogEntry\javascript\ProductDisplay.js
`DefiningAttributes_Resolved_catalogEntryID`	This event occurs when a shopper saves changes to the defining attributes of a catalog entry within the shopping cart. This event concatenates the catalog entry ID of the changed catalog entry to the event name. Subscribe to this event when your widget needs notification of the changes to specific catalog entries (SKUs) within the shopping cart.	The event publishes the catalog entry ID for the new catalog entry.	`WC_eardir`/Stores.war/Aurora/javascript/Common/ShoppingAction.js `WC_eardir`\Stores.war\Aurora\javascript\Common\ShoppingAction.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Common\ShoppingAction.js
`DefiningAttributes_Resolved_productId`	This event occurs when a shopper saves changes to the defining attributes of a catalog entry within the shopping cart. This event concatenates the product ID of the changed catalog entry to the event name. Subscribe to this event when your widget needs notification of the changes to products and specific catalog entries (SKUs) within the shopping cart.	The event publishes the catalog entry ID and the product ID for the new catalog entry.	`WC_eardir`/Stores.war/Aurora/javascript/Common/ShoppingAction.js `WC_eardir`\Stores.war\Aurora\javascript\Common\ShoppingAction.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Common\ShoppingAction.js
`ProductInfo_Added`	This event occurs after a shopper clicks the add to cart button. This event triggers when the product information is added to the shopping cart for the product the shopper added to the cart.	This event publishes the following information for the product in the array, `this.productAddedList` Product name Thumbnail Price Quantity Product attributes if selected. If the product the customer adds to the cart is a bundle, the array contains the information for each product in the bundle. The bundle information returns in a single list with multiple entries (one entry for each product that is included in the bundle).	`WC_eardir`/Stores.war/Aurora/javascript/Common/ShoppingAction.js `WC_eardir`\Stores.war\Aurora\javascript\Common\ShoppingAction.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Common\ShoppingAction.js
`Quantity_changed`	This event publishes a notification that there is a change in quantity to a product within the shopping cart.	Depending on the product details the event can publish the quantity information or publish some or all of the following information in the form of a JSON serialization string `dojo.toJson(productDetails)` Catalog entry type Catalog entry ID Quantity Price	`WC_eardir`/Stores.war/Aurora/javascript/Common/ShoppingAction.js `WC_eardir`\Stores.war\Aurora\javascript\Common\ShoppingAction.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Common\ShoppingAction.js
`DefiningAttributes_Resolved_shoppingActionsJS.baseCatalogEntryId`	This event occurs when a shopper saves changes to the defining attributes of a catalog entry within the shopping cart. By subscribing to this event a widget is notified when a shopper saves changes to the defining attributes of a catalog entry, indicating that the shopper has a different SKU within the shopping cart.	Publishes the value of the catalog entry ID of the SKU that was just added to the cart. This ID passes to the subscribing widget as the value for the parameter `shoppingActionsJS.baseCatalogEntryId`	`WC_eardir`/Stores.war/Aurora/javascript/Common/ShoppingActionsServicesDeclaration.js `WC_eardir`\Stores.war\Aurora\javascript\Common\ShoppingActionsServicesDeclaration.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Common\ShoppingActionsServicesDeclaration.js
`Facet_Remove`	This event publishes when a shopper removes a facet while they are browsing the store. Depending on the type of facet that the shopper removes, this event also publishes the ID of the removed facet. If a shopper removes a facet that uses specific values that a shopper can select, such as brand names, this event publishes the facet ID information. If a shopper removes a price filter facet, such as a shopper configured price range, the event does not publish a facet ID.	This event publishes the Facet ID If a shopper removes a facet that filters by the specific ID of facets, this event publishes the Filter ID with notification that the event occurs.	`WC_eardir`/Stores.war/`widgetdir`/com.ibm.commerce.store.widgets.CatalogEntryList/javascript/SearchBasedNavigationDisplay.js `WC_eardir`\Stores.war\`widgetdir`\com.ibm.commerce.store.widgets.CatalogEntryList\javascript\SearchBasedNavigationDisplay.js `workspace_dir`\Stores\WebContent\`widgetdir`\com.ibm.commerce.store.widgets.CatalogEntryList\javascript\SearchBasedNavigationDisplay.js
`ProductInfo_Reset`	This event occurs after a successful add to cart operation completes and the mini shopping cart window displays confirming the add to cart operation is complete. When the add to cart operation concludes, the operation clears the product information for the item added to the cart from the mini shopping cart logic. This `ProductInfo_Reset` event triggers and publishes the notification that the product information within mini shopping cart is reset or cleared. By subscribing a widget to this event, the widget can now when a shopper adds an item to their shopping cart. If the subscribing widget is tracking the item that a shopper is adding to the cart, this event provides notice that the shopper is no longer able to view the product information within mini shopping cart.	This event does not publish any parameter data that a subscribing widget can retrieve. Only notification that the event occurs passes to the subscribing widget.	`WC_eardir`/Stores.war/Aurora/javascript/Widgets/MiniShopCartDisplay/MiniShopCartDisplay.js `WC_eardir`\Stores.war\Aurora\javascript\Widgets\MiniShopCartDisplay\MiniShopCartDisplay.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Widgets\MiniShopCartDisplay\MiniShopCartDisplay.js
`ShoppingList_changed`	This event publishes when the shopper changes the information about a wish list. This event can occur when the shopper adds, edits, or deletes a wish list.	This event publishes an array that includes the following three name-value pair parameters: The wish list ID The wish list name The action that the shopper performed against the list, such as a delete action. If you subscribe a widget to this event, ensure that your widget can determine the parameter values within the array. Your widget must be capable of determining the action of the shopper against the wish list to properly use the information that this event publishes.	`WC_eardir`/Stores.war/Aurora/javascript/Widgets/ShoppingList/ShoppingListServicesDeclaration.js `WC_eardir`\Stores.war\Aurora\javascript\Widgets\ShoppingList\ShoppingListServicesDeclaration.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Widgets\ShoppingList\ShoppingListServicesDeclaration.js
`ShoppingListItem_Added`	This event publishes after a shopper adds an item to their wish list. The shopper can add the item to the wish list while they are browsing the store, or they can move an item from their shopping cart to the wish list. By subscribing to this event, a widget receives notice when the shopper adds an item to the wish list and moves an item from their shopping cart to their wish list.	This event does not publish any parameter data that a subscribing widget can retrieve. Only notification that the event occurs passes to the subscribing widget.	`WC_eardir`/Stores.war/Aurora/javascript/Widgets/ShoppingList/ShoppingListServicesDeclaration.js `WC_eardir`\Stores.war\Aurora\javascript\Widgets\ShoppingList\ShoppingListServicesDeclaration.js `workspace_dir`\Stores\WebContent\Aurora\javascript\Widgets\ShoppingList\ShoppingListServicesDeclaration.js

Publishing information for use in other widgets with Dojo events

If your custom widget must generate data for other widgets to use, you can use a Dojo event to publish the data. The other widgets can then subscribe to the published Dojo event. Use the dojo.topic.publish API to publish the Dojo event. Include the code to publish the event in your top-level JSP file. If you are publishing multiple related Dojo events through multiple custom widgets, include the code to publish the events in a single JavaScript file in a common directory. For example, if your widget tracks the breadcrumb trail, you can have your widget publish a BreadCrumb_Ready Dojo event with the data. This Dojo event is then published whenever the breadcrumb widget is loaded on a page. This event can return the breadcrumb trail information in a list that is delimited by a semicolon to other widgets. For example, Home;Apparel;Women;Dresses.

To publish an event, the following code must be included within the top-level JSP for the widget:

dojo.topic.publish('identifier_eventAction, parameter, parameter);

Where parameter is the information that is included in the event. Subscribing widgets can retrieve this information.

As another example, the Defining Attributes widget publishes the following Dojo event:

dojo.topic.publish('DefiningAttributes_Changed', catalogEntryId, productId);

This Dojo event is published whenever a defining attribute is changed and includes the catalogEntryId and productId as parameters. Subscribing widgets retrieve the SKU and parent product information whenever a shopper changes the defining attributes for a product. For example, If a shopper changes the value of the color attribute on the Product Details page, the Defining Attributes widget publishes the event. The event includes the new SKU catalogEntryId. The Full Image widget that subscribes to this Dojo event retrieves the catalogEntryId and productId information. The widget uses these new parameters to determine the correct image to display on the Product Details page.