Stencil Technology Stack

Stencil's use of Handlebars.js, JavaScript, and YAML Front Matter on the front end allows developers to create dynamic, templated customizations across a BigCommerce storefront.

Handlebars overview

Handlebars.js (opens in a new tab) is a minimal templating language that allows developers to create dynamic and robust templates for any BigCommerce Stencil storefront. A Handlebars template looks like an HTML file, with the addition of Handlebars.js expressions for dynamic logic that can be embedded into the page.

A Handlebars expression begins and end with curly braces. Below is a basic example.

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

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

View the full Handlebars Helpers Reference to learn about the helpers available on a Stencil storefront.

Stencil objects overview

Stencil objects are the individual JavaScript objects that are rendered onto a Stencil storefront. The following example is the JavaScript Object Notation (JSON) for a Banner object rendered on a category page of a storefront.

  "banners": {
    "top": [
      "For the week of May 20th, all apparel available at the online store will be 25% off the standard store price."
    ],
    "bottom": [ ],
    "top_metadata": [
      {
        "id": "3",
        "banner-name": "All Apparel 25% off for a limited time!",
        "content": "<p>For the week of May 20th, all apparel available at the online store will be 25% off the standard store price.</p>",
        "location": "top"
      }
    ]
  }

As a developer, you can use Handlebars.js syntax to access objects and use them to customize your Stencil theme.

Stencil objects are categorized as either Global, Common, or Other, which is representative of the object's scope or where in the theme it can be accessed. For example, Global Objects are components shared across the entire BigCommerce storefront.

Migration handlebars v3 to v4

Depthed paths are now conditionally pushed onto the stack. If the helper uses the same context, then a new stack is not created. Any instances of ../ in templates must be checked for the correct behavior. See handlebars.js (opens in a new tab) documentation for more information.

YAML front matter overview

BigCommerce Stencil themes utilize YAML front matter on template pages. Front matter allows developers to request objects on the storefront, allowing developers to define each page's design and layout details.

When utilized, Front Matter must be the opening text of a file and must take the form of valid YAML set between triple-dashed lines.

See our Front Matter Reference to see what Front Matter attributes are available on a Stencil storefront. Below is a snippet from the base Cornerstone theme's home.html file, showing how Front Matter can be used in a theme.

products:
  new:
    limit: {{theme_settings.homepage_new_products_count}}
  featured:
    limit: {{theme_settings.homepage_featured_products_count}}
  top_sellers:
    limit: {{theme_settings.homepage_top_products_count}}
carousel: {{theme_settings.homepage_show_carousel}}
blog:
  recent_posts:
    limit: {{theme_settings.homepage_blog_posts_count}}

Resources

Related Articles

• Handlebars.js documentation (opens in a new tab) (Handlebars)

Additional Resources

• Stencil Technology Stack Video (opens in a new tab)
• Cornerstone Components Subdirectory (opens in a new tab) (BigCommerce GitHub)