Event Hooks

Developers use “hooks” to trigger defined events. A theme can “hook” into an event to perform actions or calculations based on a shopper’s behavior.

Stencil themes incorporate event hooks by importing the stencil-utils module. Take a look at cornerstone/assets/js/theme/, and you will see the import statement ‘import utils from ‘@bigcommerce/stencil-utils’; at the top of files leveraging event hooks.

Cookie Notification Example

In the example below, the cookie-privacy-notification hook enables customization of the alert window that displays European Union-required cookie notifications.

To get started, first, ensure you have loaded the stencil-utils package with the following command:

import utils from '@bigcommerce/stencil-utils';

You can override the default browser alert box. When or why would you do this? See below.

export default function() {
  // Here you can override the default browser alert box by
  // hooking to the 'cookie-privacy-notification' hook.
  utils.hooks.on('cookie-privacy-notification', (event, privacyMessage) => {
    // You can make your own custom modal or alert box
    // appear in your theme using the privacyMessage provided
    myCustomAlert(privacyMessage);
    // Call event.preventDefault() to prevent the default
    // browser alert from occurring in stencil-utils
    event.preventDefault();
  });
}

A theme would listen for the cookie-privacy-notification event to override the browser’s default notification UI.

Cart Dialog Example

In the following code snippet from Cornerstone in_templates/components/products/product-view.html_, note the data tag named data-cart-item-add:

<form class="form" method="post" action="{{product.cart_url}}"
    enctype="multipart/form-data" data-cart-item-add>

This data tag enables the emission of the cart-item-add event in this next snippet:

/*
 * Import all product-specific js
 */
[...]
import utils from '@bigcommerce/stencil-utils';
[...]
addProductToCart() {
    utils.hooks.on('cart-item-add', (event) => {
        event.preventDefault();
    });
}

Stencil Data Tags and Event Hooks

Stencil themes provide the following chains of data tags; delegated DOM (Document Object Model) events, emitted Stencil event hooks and Stencil event parameter(s).

Cart Item Added

Hook for items added to the customer’s shopping cart.

Function Signature:

itemAdd() {
    this.$body.on('submit', '[data-cart-item-add]', (event) => {
        this.emit('cart-item-add', event, event.target);
    });
}

Faceted-Search Events

Hooks for faceted-search selections that the customer initiates or submits.

Function Signature:

searchEvents() {
  this.$body.on('click', '[data-faceted-search-facet]', (event) => {
        this.emit('facetedSearch-facet-clicked', event);
  });
  this.$body.on('submit', '[data-faceted-search-range]', (event) => {
        this.emit('facetedSearch-range-submitted', event);
  });
}

Resources

• cookieNotification.js