Stencil Utils Reference
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:
- Interact with the cart
- Use
getPageto return a template file.
Installing
As an ES6 module
- Run
npm install @bigcommerce/stencil-utilsto install the latest tagged version of stencil-utils for use with your theme. - Import the library
import utils from 'bigcommerce/stencil-utils';in modules that depend on it.
Standalone
If you do not want to support ES6 modules, Stencil Utils can be included as a normal script:
- Copy the bundled script from
dist/stencil-utils.min.jsto your theme. - Include the script in your HTML document
- Access stencil utils from
window.stencilUtils
api.js
Get page
This 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:
Get page by GraphQL
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.
Cart API
The following methods allow your theme to work with cart contents in customized ways.
Get cart
This method takes the form utils.api.cart.getCart(options, callback);.
Get cart quantity
Get a sum of the cart line item quantities. It takes the form utils.api.cart.getCartQuantity(options, callback);.
Usage in Cornerstone
Item add
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.
Usage in Cornerstone
Item update
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);.
Usage in Cornerstone
Item remove
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.
Usage in Cornerstone
Update
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:
Get item gift wrapping options
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.
Usage in Cornerstone
Submit item gift wrapping option
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);.
Get content
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.
Usage in Cornerstone
- assets/js/theme/global/cart-preview.js
- assets/js/theme/cart.js
- assets/js/theme/common/product-details.js
Get shipping quotes
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.
Usage in Cornerstone
Submit shipping quote
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.
Usage in Cornerstone
Apply code
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:
Usage in Cornerstone
Apply gift certificate
This method applies a gift certificate to a cart. It takes the form utils.api.cart.applyGiftCertificate(code, callback);.
The following example calls appleGiftCertificate.
Usage in Cornerstone
Countries Resource
These methods allow your theme or app to retrieve standardized country names, by numeric ID or by string.
Country get by id
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.
Get by name
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:
Usage in Cornerstone
Product Attributes Resource
Option change
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.
Usage in Cornerstone
Configure in cart
This method configures product options in the cart. It takes the form utils.api.productAttributes.configureInCart(itemId, options, callback);.
Usage in Cornerstone
Product Resource
Product get by id
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);.
Usage in Cornerstone
Search Resource
The search method allows you to present a customized user interface for search results.
Search
The core search method takes the form utils.api.search.search(query, params, callback);.
Usage in Cornerstone
Config Object
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.