JavaScript events

This guide covers all JavaScript events that the Maranello theme fires before or after various user actions, along with any possible data returned from each event.

Subscribing to an event

Maranello uses a simple pub sub pattern for handling all events. To listen to an event, use the subscribe function. This function takes two parameters:

• eventName: A string that identifies the event to which you want to subscribe.
• callback: The function to be executed when the event is fired.

The subscribe function is globally available and returns another function that can be used to unsubscribe from the event. This is handy for cleaning up event listeners when they are no longer needed.

Here is an example of subscribing to an event:

const cartItemAddUnsubscribeHandler = subscribe(PUB_SUB_EVENTS.cartItemAdd, (data) => {
	console.log("Item added to cart: ", data);
});

In the example above, we subscribe to the cartItemAdd event, and we provide a callback function that logs a message to the console whenever this event is fired.

If you need to unsubscribe to this event at any point simply call the returned function:

cartItemAddUnsubscribeHandler();

Subscribing to an event

In the case where you want to create and publish your own events, or publish the existing events in other instances use the publish function. This function takes two parameters:

• eventName: A string that identifies the event you want to publish.
• data: The data you want to pass to the subscribers of the event.

Here is an example of publishing an event:

publish(PUB_SUB_EVENTS.cartItemAdd, { itemID: 1234, quantity: 1 });

In the example above, we publish the cartItemAdd event, and we pass an object with itemID and quantity properties to all subscribers of this event.

Event names

The PUB_SUB_EVENTS object (available globally) that is defined in the file assets/pubsub.js contains predefined names for various events fired throughout your store’s lifecycle (i.e. adding or removing products, updating the cart, etc). Using this object makes your code more predictable and less prone to bugs caused by typos. You can use this object to refer to event names, rather than using string literals.

The following events are baked into the theme and a lot of them will also provide additional data based on the action that was taken in the form of a data object. In such a case they are documented under each event.

cart:item-add (PUB_SUB_EVENTS.cartItemAdd)

This event fires any time a product is added to the cart, regardless of where it was added from. A special source in the event’s data object provides more information on which section the product was added from.

Additional data:

{
  source: string; The section where the product was added. See available values below.
  items: object[]; An array containing the cart items added as returned from Shopify's API.
}

Available values for data.source:

MainProduct
FeaturedProductSection
ProductCardProductRecommendations
ProductCardCollectionTabsSection
ProductCardCustomRelatedProductsSection
ProductCardFeaturedCollectionSection
ProductCard - Collection: {CollectionName}
ProductCardSearchPage
ProductCardComplementaryProducts

cart:item-error (PUB_SUB_EVENTS.cartItemError)

This event fires whenever there is an error in the cart (i.e. when there’s an error after adding a product, or when updating the cart).

Additional data:

{
  productVariantId: string; The product's variant id (if the error occurs after adding a product).
  errors: object; An error object containing the cart errors.
  message: string; A string describing the error.
}

cart:item-quantity-update (PUB_SUB_EVENTS.cartItemQuantityUpdate)

This event fires whenever a product’s quantity is updated in the cart. Currently there are two places this can be done from, both documented as source in the event’s data.

Additional data:

{
  source: string; The section from which the action was taken.
  cart: object; The cart object as returned from Shopify's API.
}

Available values for data.source:

MainCart
CartPage

cart:item-remove (PUB_SUB_EVENTS.cartItemRemove)

This event fires whenever a product is removed from the cart. Currently there are two places this can be done from, both documented as source in the event’s data.

Additional data:

{
  source: string; The section from which the action was taken.
  cart: object; The cart object as returned from Shopify's API.
}

Available values for data.source:

MainCart
CartPage

collection:filters (PUB_SUB_EVENTS.collectionFilters)

This event fires any time user changes the product filters on any collection or search page.

Additional data:

{
 filters: Object; An object containing the names of the filters that are selected.
}

header-cart:close (PUB_SUB_EVENTS.headerCartClose)

This event fires any time the header’s cart modal closes. It has no additional data.

header-cart:open (PUB_SUB_EVENTS.headerCartOpen)

This event fires any time the header’s cart modal opens. It has no additional data.

header-search:close (PUB_SUB_EVENTS.headerSearchClose)

This event fires any time the predictive search modal in the header closes. It has no additional data.

header-search:open (PUB_SUB_EVENTS.headerSearchOpen)

This event fires any time the predictive search modal in the header opens. It has no additional data.

mobile-menu:close (PUB_SUB_EVENTS.mobileMenuClose)

This event fires any time the mobile menu drawer closes. It has no additional data.

mobile-menu:open (PUB_SUB_EVENTS.mobileMenuOpen)

This event fires any time the mobile menu drawer opens. It has no additional data.

page:change (PUB_SUB_EVENTS.pageChange)

This event fires whenever the page is changed in a collection or search template when the “Products pagination” setting is set to “Ajax pagination”.

Additional data:

{
  page: number; The number of the new page.
}

pickup-availability-drawer:close (PUB_SUB_EVENTS.pickupAvailabilityDrawerClose)

This event fires any time the pick availability drawer closes in the main product template. It has no additional data.

pickup-availability-drawer:open (PUB_SUB_EVENTS.pickupAvailabilityDrawerOpen)

This event fires any time the pick availability drawer opens in the main product template. It has no additional data.

product:modal-close (PUB_SUB_EVENTS.productModalClose)

This event fires any time the main product image modal opens. It has no additional data.

product:modal-open (PUB_SUB_EVENTS.productModalOpen)

This event fires any time the main product image modal opens. It has no additional data.

product:quantity-update (PUB_SUB_EVENTS.productQuantityUpdate)

This event fires any time the user changes the product quantity in the main product template or the featured product section.

Additional data:

{
  quantity: number; A number representing the quantity input's value after the change.
}

product:variant-change (PUB_SUB_EVENTS.productVariantChange)

This event fires any time the user changes the variant in the main product template or the featured product section.

Additional data:

{
  sectionId: The HTML ID of the section that triggered this event.
  html: The HTML returned from the server after the variant is changed.
  variant: Object; The variant that was selected.
}

search-results:close (PUB_SUB_EVENTS.searchResultsClose)

This event fires any time the predictive search contents close. It has no additional data.

search-results:open (PUB_SUB_EVENTS.searchResultsOpen)

This event fires any time the predictive search contents open. It has no additional data.

slider:slide-change (PUB_SUB_EVENTS.sliderSlideChange)

Desktop only. This event fires whenever a slide occurs when the “Slider” layout option is enabled in the following sections: Banner list, Brands, Collection list, Collection tabs, Featured collection, Promotion blocks, Simple collection list.

Additional data:

{
  id: string; The slider's element ID.
  index: number; 0-based index of the slide that was navigated to.
}

slideshow:slide-change (PUB_SUB_EVENTS.slideshowSlideChange)

This event fires whenever a slide change occurs in the Slider section.

Additional data:

{
  id: string; The slider's element ID.
  index: number; 0-based index of the slide that was navigated to.
}