Knowledge Base

An Introduction to Handlebars

Last Modified:
23 Apr 2024
User Level:

Handlebars is a versatile templating engine designed to simplify the process of creating dynamic content. For those who are unfamiliar with Handlebars, think of it as a tool that bridges the gap between static HTML and dynamic data.


Handlebars allows you to create Content Layouts and Page Layouts with placeholders and simple logic that will be filled in with data at Publish time, making it easier to manage and manipulate content in ways that are not possible using standard T4 Tags without needing extensive coding expertise or familiarity with the complexities of Programmable Layouts.

One of the key features of Handlebars is its simplicity. With a syntax that closely resembles regular HTML, users can quickly grasp the basics and start building more "dynamic" Content types and Page layouts.

Handlebars uses double curly braces {{}} to denote placeholders, which are then replaced with actual data when the layout is Published – much like the t4 tags you may be familiar with today.

The Terminalfour implementation of Handlebars comes with an extensive toolkit of "Helpers" to allow you to add logic to your layouts in a way that just isn't possible with t4 tags.

From Terminalfour 8.3.19 you can make use of Handlebars by selecting it as a processor type on your Page Layouts and Content Layouts:

A screenshot of the General Tab when creating a Content Layout showing Handlebars is now an option in the Processor dropdown

Before we dive in...

8.3.19 is our initial release of Handlebars and we'll be extending the functionality and improving the experience over the next several releases of the platform.

Before we explore how Handlebars works it's important to mention a few items up front to help you make the best use of the feature.

Mixing t4 tags and Handlebars expressions

When setting the Content layout processor to Handlebars Content you can no longer use "T4 tags" in the layout. Instead you must use the handlebars helpers outlined in the rest of this guide.

Error handling

Like with standard T4 tag based layouts and programmable layouts it's possible to configure things incorrectly and get undesired or unexpected results.

Preview & Direct Edit

When an error is encountered with a Handlebars layout during Preview or Direct Edit we output an inline error message on the page to users.

This error is in the form of a table and displays the following info:

  1. The Section ID where the error is occurring
  2. The asset language
  3. The Content ID (if applicable)
  4. The error message
  5. The content layout name (if applicable)
  6. The layout code (if applicable)

This should give you enough information to find out where the problem exists so you can debug.


An example of a Handlebars error in previewPublish

When a Publish happens and an error is encountered we could have done one of two things:

  1. We could ignore the error, and continue the Publish
  2. We could stop the publish to prevent breaking the live site

Both have their pros and cons and ultimately we'll need to hear from you, our users, about how you're using Handlebars to determine the best long term solution.

For now, we've taken the safest and least destructive option which is to fail the publish. This means if you accidentally introduce a breaking error in your most commonly used Content Type or Page Layout we'll prevent that error from getting pushed to your live site and ultimately breaking a significant portion of your web pages.

When the publish fails it does so with very clear messaging in the logs explaining the reason for the failure.


An. excerpt of the logs showing publish errors

Direct Edit

In the initial release of Handlebars, it does not support inline editing with Direct Edit.

However, the Handlebars feature was designed with Direct Edit in mind, and we aim to bring inline editing to an upcoming release of Terminalfour.

How to use handlebars

Ok, with that out of the way, let's see what's involved in using handlebars:

Getting started

Back to top