Stencil Utils is a utility library that contains the BigCommerce Stencil Events system and other methods that make building a theme with the Stencil framework a breeze.
These methods help you set up asynchronous requests to modify the customer’s cart or storefront view. By using this abstraction library, you can gain more-granular control over themes’ presentation. Use stencil-utils to:
getPage to return a template file.npm install @bigcommerce/stencil-utils to install the latest tagged version of stencil-utils for use with your theme.import utils from 'bigcommerce/stencil-utils'; in modules that depend on it.If you do not want to support ES6 modules, Stencil Utils can be included as a normal script:
dist/stencil-utils.min.js to your theme.window.stencilUtilsThis method takes the form utils.api.getPage(url, options, callback).
The config argument works like front matter: it encapsulates JSON. For a usage example of config, see the Remote API Example.
In the following example from common/faceted-search.js, an updateView() method uses api.getPage() to refresh page content.
The Cornerstone theme uses the getPage method in the following contexts:
This method takes the form utils.api.getPageByGQL(page, callback).
It allows you to render parts of a template using an inline GraphQL query, as shown in Front Matter Reference - GraphQL attributes.
The following methods allow your theme to work with cart contents in customized ways.
This method takes the form utils.api.cart.getCart(options, callback);.
Get a sum of the cart line item quantities. It takes the form utils.api.cart.getCartQuantity(options, callback);.
The itemAddmethod allows your code to add an item to the cart, with options. This method takes the form utils.api.cart.itemAdd(FormData, callback);.
itemAdd is called at the head of the following example (from common/product-details.js) to populate the cart.
The itemUpdate method allows your code to update a specified cart item’s quantity. This method takes the form utils.api.cart.itemUpdate(itemId, qty, callback);.
The itemRemove method allows your code to remove items from the cart. This method takes the form utils.api.cart.itemRemove(itemId, callback);.
In the following example (from cart.js), itemRemove is called before the if/else test.
The update method allows your code to update the set of items in the cart. It takes the form utils.api.cart.update(itemId, qty, callback);.
The following example shows a call to update within the itemUpdate method:
The getItemGiftWrappingOptions method allows your code to retrieve gift-wrapping options for the current cart item, in customized ways. It takes the form utils.api.cart.getItemGiftWrappingOptions(itemId, callback);.
The following example (from cart.js) calls getItemGiftWrappingOptions to display gift-wrapping options in a modal.
The submitItemGiftWrappingOption method allows your code to handle the customer’s gift-wrapping selection for the current cart item. This method takes the form utils.api.cart.submitItemGiftWrappingOption(itemId, qty, callback);.
The getContent method allows your code to display the cart contents in customized ways. It takes the form utils.api.cart.getContent(options, callback);.
This example (from cart.js) shows a call to getContent within the refreshContent function.
The getShippingQuotes method allows your code to retrieve shipping-cost quotes for the cart’s contents. It returns shippingQuote objects that contain IDs. You must follow getShippingQuotes by calling submitShippingQuote on a quoteId. This method takes the form utils.api.cart.getShippingQuotes(params, renderWith, callback);.
See submitShippingQuotes for an example.
This method takes the form utils.api.cart.submitShippingQuote(quoteId, callback);.
The submitShippingQuote method must be called after getShippingQuote, which returns shippingQuote objects that contain IDs. The cart page renders the shipping quotes. When the user selects one of the quotes, this method sends that quoteId to the backend.
The following example from cart/shipping-estimator.js shows calls to both getShippingQuotes and submitShippingQuote.
The applyCode method applies a coupon code or gift certificate to the cart. It takes the form utils.api.cart.applyCode(code, callback);.
In the following example from cart.js, applyCode is called before the final if/else test to apply a coupon code:
This method applies a gift certificate to a cart. It takes the form utils.api.cart.applyGiftCertificate(code, callback);.
The following example calls appleGiftCertificate.
These methods allow your theme or app to retrieve standardized country names, by numeric ID or by string.
The country getById method retrieves standardized country names by numeric ID. This method takes the form utils.api.countries.getById(countryId, callback);.
The following example makes a call to country getById.
The getByName method retrieves states by country name, and returns an array of states that can be used in the callback. It takes the form utils.api.countries.getByName(countryName, callback);.
In the following example from common/state-country.js, getByName is called after the initial if test:
The optionChange method is fired when the customer selects a product option for the current cart item (for example, changing a shirt’s color from a default “yellow” to “green”). This method takes the form utils.api.productAttributes.optionChange(productId, params, callback);.
In this example (from common/product-details.js), optionChange is called to update options in a Quick View modal.
This method configures product options in the cart. It takes the form utils.api.productAttributes.configureInCart(itemId, options, callback);.
The product getById method allows your code to retrieve, and to present, detailed product information by product ID. This method takes the form utils.api.product.getById(productId, params, callback);.
The search method allows you to present a customized user interface for search results.
The core search method takes the form utils.api.search.search(query, params, callback);.
A config object can be passed in as part of the Stencil Utils API.
The object only returns data in the context of that call. The config will not be available to anything else. It will not surface objects that are not normally available to the page. Use YAML to return objects in the context of an entire page. Some config objects can only be used on the listed pages, while others are available globally.