Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars Syntax and Helpers
Handlebars.js
Handlebars Helpers
Stencil Object Model
Stencil Objects

Handlebars.js Overview

Handlebars.js

Handlebars is a minimal templating language that allows you to create dynamic and robust templates for any BigCommerce storefront. 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">
<div class="entry">
  <h1>{{ title }}</h1>
  <div class="body">
    {{ body }}
  </div>
</div>

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

For a thorough overview of how to use Handlebars inside your templates, please review the Handlebars documentation and tutorials located at http://handlebarsjs.com/.

Template Logic

With Handlebars, it’s easy to embed logic right into your templates. Handlebars has built-in helpers for widely used logic and iterator functions. You can find a list of all built-in Handlebars helpers here.

Custom Handlebars Helpers

BigCommerce has extended the built-in Handlebars helpers with certain custom Handlebars helpers. For details, please proceed to the reference section.

Stencil Handlebars Resources

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

Rendering Special Characters

By default, Handlebars HTML-escapes values returned by a Handlebars {{ expression }}. So, where a Handlebars expression’s referenced content includes special characters, those characters will render literally on the storefront as HTML entities.

In the example above, assume that the HTML referenced by {{ title }} contains an ampersand and a “straight” apostrophe. You will see the entities & and ’ 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, like this: {{{ title }}}. Handlebars documentation refers to this technique as a “triple-stash.”