Technical - Event API

Infinite Options' Event API allows developers to tie in to and react to different processes that occur within Infinite Options. This article contains information on how to subscribe to certain actions, as well some context on what you can do with these events.

Note: This includes technical information. Knowledge of the JavaScript language is required.

Subscribing to events

Events are subscribed to by calling the subscribe method before the app has ran. The subscribe method takes two arguments, a string matching the name of the event (events are listed below), and a callback function that takes a single argument, event. In order to access this method, you will need to tie into the beforeReady callback. Here's an example of this:

<script>
  // Create "window.Shoppad.apps.infiniteoptions" object if it doesn't already exist
  "Shoppad.apps.infiniteoptions".split(".").reduce(function(o, x) { if (!o[x]) {o[x] ={};} return o[x] }, window);

  // Define beforeReady callback
  window.Shoppad.apps.infiniteoptions.beforeReady = function(subscribe) {
    subscribe('appLoad', function(event) {
      console.log('appLoad', event);
    });
  };
</script>

Note: You will need to define the beforeReady callback before the app has loaded. If you are explicitly loading the script using the instructions found in this article, you will need to define the callback before that script is called. If you aren't explicitly loading the app, defining the callback anywhere in the <head /> will suffice.

Events

Here's a list of all the available events.

appLoad

Fired when all fields have been added to the DOM and the app has run its initial processing.

/**
 * @param {object} event
 * @param {array} event.detail.fields An array of arrays, with each array being an option set that applies to the current product.
 * @param {boolean} event.detail.hasConditionalLogic True if conditional logic is active on this product, false if not.
 * @param {boolean} event.detail.hasBundledProducts True if the initial state of app has product bundles attached.
 */
subscribe('appLoad', function(event) {
  console.log('appLoad', event);
});

fieldLoad

Fired every time a field is added to the DOM.

/**
 * @param {object} event
 * @param {string} event.detail.name The field name of the input.
 * @param {string} event.detail.value The value of the input.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 * @param {object} event.detail.fieldConfig 
 * @param {boolean} event.detail.hasConditionalLogic True if the field utilizes conditional logic.
 * @param {boolean} event.detail.hasBundledProducts True if the field has product bundles attached in its initial state.
 */
subscribe('fieldLoad', function(event) {
  console.log('fieldLoad', event);
});

fieldChange

Fired every time a field is changed. To be specific, this is fired when the native change event is fired for select menus, checkboxes, radio button, and when the keyup / touchend event is fired for text areas, text inputs, and number inputs. 
/** 
 * @param {object} event
 * @param {string} event.detail.name The field name of the input.
 * @param {string} event.detail.value The value of the input.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 */
subscribe('fieldChange', function(event) {
  console.log('fieldChange', event);
});

productBundleAdd

Fired when a product bundle is selected (can occur on page load). 
/**
 * @param {object} event
 * @param {string} event.detail.name The field name of the input.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 * @param {object} event.detail.productBundle Details about the bundled product.
 */
subscribe('productBundleAdd', function(event) {
  console.log('productBundleAdd', event);

  // Note: The product variant price returned is cached. You may want to retrieve the latest price.
  window.Shoppad.apps.infiniteoptions.getLatestVariantPrice(event.detail.productBundle, function(productBundle) {
    console.log('Latest productBundle price', event);
  });
});

productBundleRemove

Fired when a product bundle is unselected (can occur on page load). 
/**
 * @param {object} event
 * @param {string} event.detail.name The field name of the input.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 * @param {object} event.detail.productBundle Details about the bundled product.
 */
subscribe('productBundleRemove', function(event) {
  console.log('productBundleRemove', event);

  // Note: The product variant price returned is cached. You may want to retrieve the latest price.
  window.Shoppad.apps.infiniteoptions.getLatestVariantPrice(event.detail.productBundle, function(productBundle) {
    console.log('Latest productBundle price', event);
  });
});

fieldShow

Fired every time a field is shown. 

/**
 * @param {object} event
 * @param {string} event.detail.name The field name of the input.
 * @param {string} event.detail.value The value of the input.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 */
subscribe('fieldShow', function(event) {
  console.log('fieldShow', event);
});

fieldHide

Fired every time a field is hidden (can occur on page load). 

/**
 * @param {object} event
 * @param {string} event.detail.name The field name of the input.
 * @param {string} event.detail.value The value of the input.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 */
subscribe('fieldHide', function(event) {
  console.log('fieldHide', event);
});

productBundleCartSubmit

Fired when product bundles are attached and the user submits the main product's cart.

Note: This event is cancelable. Call event.preventDefault(); to prevent the app from submitting the main product's form after product bundles have been submitted. 

/**
 * @param {object} event
 * @param {array} event.detail.submittedProducts The products that were submitted to the cart.
 */
subscribe('productBundleCartSubmit', function(event) {
  console.log('productBundleCartSubmit', event);
});

validationSuccess

Fired when validation for fields has passed. 

/**
 * @param {object} event
 */
subscribe('validationSuccess', function(event) {
  console.log('validationSuccess', event);
});

validationFail

Fired when validation for fields has failed.

Note: This event is cancelable. Call event.preventDefault(); to prevent an alert with the error message from showing. 

/**
 * @param {object} event
 * @param {string} event.detail.error The error message for the input that failed validation first.
 * @param {object} event.detail.element A jQuery object representing the element that added to the DOM (this is the parent <div> that wraps the input and label).
 */
subscribe('validationFail', function(event) {
  console.log('validationFail', event);
});