5 Handlebars Helpers BigCommerce Developers Should Know

Kyle O’Brien
Dec 5, 2019 · 5 min read

The Stencil theme platform enables developers to control store data flow from the BigCommerce back-end to the front-end. Developers can direct the presentation of each page using Handlebars Helpers. There are various examples of this throughout the Cornerstone theme: where product fields are assembled, templates/components/products/product-view.html, the account page’s list of previous orders, templates/components/account/order-contents.html.

In this blog post, we’re going to focus on five underutilized Handlebars Helpers that might be helpful for everyday programming tasks. Starting with the string helpers {{json}} and {{concat}}, these offer string access or modification when developers would commonly need to make a tedious change with scripting. Building on that with the {{moment}} helper, we’ll learn how to cache-bust an image using the current moment as a parameter. Afterward, we invoke {{filter}} to display a custom component. Finally, we wrap up with {{jsContext}} and its broad appeal for various applications. As an example, we’ll inject related product IDs into the jsContext and console log the results.

It’s important to note that Handlebars should only be used in .html files, if found elsewhere the code will display unchanged or possibly invite unexpected errors into the codebase. To check which objects are available in a page’s context, add the parameter ?debug=bar to the localhost URL when running the Stencil CLI.

{{json}}

We can see what {{json blog}} returns on the home page of a sandbox store.
We can see what {{json blog}} returns on the home page of a sandbox store.
We can see what {{json blog}} returns on the home page.

This is a custom helper added with our built-in paper-handlebars plugin that converts a JavaScript object into a json string. I’ve seen {{json}}commonly used when working with Stencil objects to quickly test what is returned in a given context, which is where the json Handlebars Helper shines.

If you’re trying to add blog posts to the home page, you can quickly see what the blog object returns on /templates/pages/home.html by adding {{json blog}} to that file.

Find more examples of objects available for use with the json helper on our developer documentation here.

{{concat}}

<h1 class=”productView-title” {{#if schema}}itemprop=”name”{{/if}}>{{concat product.title product.sku}}</h1>

We can see the result in the following screenshot. Note the SKU “CLC” is placed immediately after the product title “Canvas Laundry Cart”, without space between.

A screenshot of our {{concat}} example in action on a product page.
A screenshot of our {{concat}} example in action on a product page.
Our {{concat}} example in action on a product page.

{{moment}}

<img src=”/content/home-hero.jpg?{{moment}}”/>

Our CDN will use that asset’s first chronological upload, which can cause problems when testing and replacing files in real-time. By using {{moment}}as a parameter, the latest version is retrieved instead. This is called cache-busting. To retain benefits gained from using our CDN, developers should focus on specific, frequently-updated resources such as an advertising banner. In contrast, developers would not cache-bust a store logo that is rarely updated.

Any resource served this way will lose the benefits of our CDN, discretion should be exercised with the moment helper.

{{filter}}

{{#filter product.custom_fields ‘Bulk Shipping Dimensions’ property=’name’ }}{{> (concat ‘components/bulk-dim/’ value) }}{{else}}Bulk Shipping not available.{{/filter}}

This also uses the concat helper we learned earlier. The joined strings here are the product’s value for the custom field ‘Bulk Shipping Dimensions’, expecting a component with the same value in the ‘components/bulk-dim’ directory of the theme. Excluded from this example, I created an .html file with the same value as the product’s Bulk Shipping Dimensions. If the matching value exists, the component will be displayed as a partial. Otherwise, the message below {{else}} appears.

Screenshot of the product edit page on BigCommerce, a custom field matching the code has been added.
Screenshot of the product edit page on BigCommerce, a custom field matching the code has been added.
A value of ‘small’ has been added to the custom field “Bulk Shipping Dimensions”. This product will expect a small.html to be found in components/bulk-dim when loaded on the storefront because of our changes.
What our component looks like on a sandbox store, as well as description-tabs.html.
What our component looks like on a sandbox store, as well as description-tabs.html.
What our component looks like on a sandbox store, compared to our changes to description-tabs.html.

{{jsContext}}

{{inject “productIds” (pluck product.related_products “id”)}}<script>const pageContext = JSON.parse({{jsContext}});console.log(pageContext[‘productIds’]);</script>

This console logs the product IDs within the current context. It’s worth noting in this example when using {{inject}} the pluck helper is also invoked. This is to return the corresponding value, in this example being the related_products’ IDs.

{{jsContext}} returns values specified with {{inject}} for requested attributes, but without an injection we can see what the default jsContext is above.

Conclusion

I’m curious how others would use these helpers creatively. Share your ideas below and let us know how you’ve applied Handlebars Helpers to your Stencil themes lately.

BigCommerce Developer Blog

News, tips, and stories for developing on BigCommerce

Kyle O’Brien

Written by

Developer Community Moderator @BigCommerce

BigCommerce Developer Blog

News, tips, and stories for developing on BigCommerce

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade