Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars.js Overview
Handlebars Helpers
Stencil Object Model
Stencil Objects

Handlebars.js Overview


Handlebars.js is a minimal templating language, offering helpers that allow you to create dynamic and robust templates for any BigCommerce storefront. Alongside the standard helpers offered by Handlebars.js, BigCommerce has added a variety of custom helpers available for use. For example, in Array Helpers you will see two types of helpers: Standard Array Helpers, which are the existing Handlebars.js helpers, and Custom Array Helpers, which are BigCommerce’s extension of the helpers.

A Handlebars template looks just like a regular HTML page, with the addition of Handlebars expressions for all dynamic logic that you embed into the page.

A Handlebars expression begins with: {{ and ends with: }}.

Here is a basic example that accesses the title and body variables:

<div class="entry">
  <h1>{{ title }}</h1>
  <div class="body">
    {{ body }}

In production, Handlebars statements run on the server side, generating HTML received by the shopper’s browser.

You can view a full reference page of all the handlebars helpers available to Stencil here, or explore them using navigation on the left hand side.

For a thorough overview of how to use Handlebars inside your templates, review the Handlebars documentation (Handlebars).

Template Logic

With Handlebars, it’s easy to embed logic right into your templates. Handlebars has built-in helpers for widely used functions.

Stencil Handlebars Resources

For a comprehensive reference to the Stencil data objects that you can manipulate via Handlebars statements, see the Stencil Object Model Reference.

Rendering Special Characters

By default, Handlebars HTML-escapes values returned by a standard Handlebars {{expression}}. So, if a Handlebars expression includes special characters, the character codes will render literally on the storefront as HTML entities as opposed to producing the character itself.

Assume that the HTML title referenced by the{{title}} Handlebars expression contains an ampersand and a straight apostrophe. When this helper renders on the storefront, you will see the character codes &amp; and &#039; displayed literally on the storefront, instead of the intended characters & and '. Similar display errors will be triggered by apostrophes, quotation marks, primes, and other extended characters. The workaround is to place the Handlebars variable in triple braces, i.e. {{{title}}}. Handlebars documentation refers to this technique as a “triple-stash.”