Using BigCommerce Storefront APIs to Create Custom Product Display Page Experiences
When developing custom Stencil themes and behaviors, BigCommerce’s Storefront APIs are a great tool for enhancing experiences with client-side code. The Storefront API allows developers to manage a shopper’s cart, which retrieves product data via JavaScript. On the Product Display Page, this API gives you the capability to augment products in a non-persistent environment and eases the process of making complex changes.
Getting Started
If you’re not yet familiar with BigCommerce APIs, I recommend getting started by reviewing our documentation for custom templates and mapping custom templates to JavaScript modules. Our Dev Center also has a guide for Working with Storefront APIs to test out these endpoints.
Here on the BigCommerce Developer Blog, we‘ve previously shared examples on how to use Storefront APIs for advanced use cases. In Brian Davenport’s article, “Build a Bulk Order Form using the BigCommerce Storefront API and React,” he demonstrates a React-based approach to creating intricate carts. If you haven’t tried applying your React skills to a Stencil template yet, Patrick Puente’s article, “Create Custom BigCommerce React Templates with Stencil” is another great resource to check out. Patrick lays the groundwork for creating a modified developer environment that supports React components and implementing a custom template to pass props.
Creating a Custom Product Display Page
For this tutorial, we are using fetch to access the Storefront Cart API and add multiple items to the cart with vanilla JavaScript. We use a Storefront API to accomplish this because we’re making changes on the front-end with publicly-accessible product info so no back-end work is necessary. Our goal is to create a pseudo bundle or “multi-product” by combining the Stencil framework’s custom templates and the Storefront Cart API. We’ll also use the GraphQL Storefront API to display included products on the Product Display Page (PDP).
You can see a live example on my sandbox store here, or if you’d prefer: skip to the code.
Custom Templates and Components
Custom fields are commonly used by merchants to enrich product details and should be reserved for public-facing product info. Metafields can be used for arbitrary information that you may want to hide. While there isn’t currently a public-facing Storefront API available to access Metafields for the app we’re creating today, using Metafields is the recommended long-term strategy for fields like this. I’ll use custom fields as a short-term solution until my app can be updated with Metafields.
The custom field names I decided to use were “is_bundle” and “foo”, where the template will check if the “is_bundle” value is “true”, and “foo” will be assigned a product ID. “foo” is only used in the code, so it isn’t displayed for customers, but I recommend updating it for your implementation so that it’s meaningful. Our custom components will be aptly located in the /templates/components/custom directory, which will need to be created if you don’t already have one. I recommend using a “custom” folder to easily track which components were added to a theme.
To get started, let’s create a custom product page template to assign to products that will add multiple items to the cart. You can find more about creating custom templates on the BigCommerce DevCenter here. I created the multi-layout.html file below with a modified version of product.html:
The majority of the original template has been removed and now references `{{ > components/custom/multi-view}}`, a new component we’ll add next. To make the custom PDP extensible I created a new product component, which could be added on to other implementations.
Within multi-view.html you’ll first see two inject Handlebars Helpers and an empty array called “arr” 🏴☠️ keep this in mind for later since we aren’t ready to load any products yet.
This is based on product-view.html and I’ve truncated duplicate code with `[…]` to focus on the changes. In the first couple of lines, steps are taken to implement our JavaScript module that imports GraphQL and displays product data, and we’ll get back to that soon. If you skip to near the bottom you’ll see another custom component being called through a Handlebars partial: {{> components/custom/multi-button}}. Let’s now look at multi-button.html to see how the Storefront Cart API is executed before continuing with “multi-view”.
Implementing the Storefront API with Fetch
The bulk of logic for adding multiple items to the cart is handled through the multi-button component’s related JavaScript. A function I named “addMultiToCart” is declared in a JavaScript module file, custom.js, that also loads the aforementioned GraphQL product data. Following the method described on the BigCommerce DevCenter here, assets/js/theme/custom.js is mapped as a module for a few reasons.
Implementing these APIs with fetch can make it seem easy, but we’re also neglecting any browsers that lack compatibility (I’m looking at you, IE!). This can be fixed by loading in a module like polyfill or node-fetch to take care of that for you, which can be installed and imported like a normal npm dependency. Here I opt for node-fetch.
In the multi-button.html file, you’ll find Handlebars used to determine if our custom button should appear for the current product using the “is_bundle” custom field. This could be used similarly on the default product page as I briefly mentioned earlier. The button is assigned a different ID (#multiButton) to ensure this script doesn’t impact typical add-to-cart buttons, as well as a custom value (Combo to Cart) for display purposes.
Our “addMultiToCart” function has two arguments: the required product IDs and optional cart ID, but relies on the multi-button component for its input with an id of “multiButton”. Here’s what that looks like executed with vanilla JavaScript in custom.js:
After the function is declared, we select that specified ID to add an event listener which runs the loaded “addMultiToCart” function with an array of Product IDs and any available cart ID once the button is clicked.
Displaying Product Data with the GraphQL Storefront API
Now that we’ve seen how the products are being added to a cart, let’s go back to the top of multi-view.html. We have the following:
This first iterates for each custom_field within the given product’s context, checking if the field’s name is “foo”. If it is, use the Handlebars Helper {{inject}} with the value for the current page’s context. Remember that empty array called “arr” I pointed out earlier (reminder)? We’re going to push the value from the page’s context into that array since we can access the value now via JavaScript. More info on using injection helpers can be found on the dev docs here.
Now that the “foo” values/product IDs are all in an array, we can use the GraphQL Storefront API to retrieve each product’s info. For this example, I’ve used some of the code shared by Nathan Booker on our dev docs, and the source can be found on GitHub.
The script selects an ID I assigned to an element, #multi-desc, and appends the returned HTML data by the GQL SF API to the innerHTML of that element. This was an added feature to create a stark visual contrast between this and other products. It also introduces the concept for future iterations where completely customized product pages could be displayed in a way that makes sense for their respective placeholder product.
To display these products more naturally, I added CSS via assets/scss/multi-layout.scss, and to learn more about adding CSS to your theme check out our dev doc here.
Conclusion
Devs looking to completely customize the Product Display Page experience can use this as a specific example, but I encourage readers to build on this knowledge. My implementation of the Storefront Cart API bypasses the typical quick-view.html the Cornerstone theme uses after adding an item to the cart, which would require additional customization.
BigCommerce’s Storefront APIs offer developers functionality not available in the Stencil framework to further personalize a customer’s experience. To create a special Stencil template, combine the Storefront Cart API with another tool like the GraphQL Storefront API as we saw in our example today.
Have you used one of our Storefront APIs with a Stencil theme lately? Let us know on the @BigCommerceDevs Twitter or comment below!
