Getting Started with handlebars

Last Modified:: 22 Nov 2024
User Level:: Power User

Description

The following document assumes some knowledge of T4 tags and uses T4 tags to explain how Handlebars will function.

If you'd like to attend Handlebars Training, get in touch with us!

Instead of using T4 tags with Handlebars content, you can now use handlebars expressions by selecting Handlebars content when choosing a processor type on your Content or Page Layouts.

Handlebars expressions (or Helpers) use 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.

This document will aim to give you the basics you need in order to start building your layouts with Handlebars.

Ensure you've read the Handlebars overview in full before continuing.

There are a number of different "Helpers" which can be used to output data or apply logic.

Let's start with the most basic:

publish Helper

The publish Helper is used in Content layouts to output the elements of a Content type.

Using the publish Helper to output a plain text element called "Title":

The equivalent T4 tag would be:

A key thing to note is that when using the publish Helper is that it will not process any HTML and instead will output the HTML encoded equivalent by default.

If you need the output the data as HTML (for example, if you're using a HTML element, or if it's a Plain text element being used to output "Code") then you would use triple curly braces {{{}}} .

Using the publish Helper to output an HTML element called "Main content":

{{{publish element="Main content"}}}

The equivalent T4 tag would be:

You do not need to add any additional parameters or "modifiers" in order for Media, or links to be published. This happens automatically.

You can use the publish Helper in conjunction with the String Manipulation helpers outlined below to further control the output of Plain text and HTML elements.

link Helper

The link Helper is used to give you more control around how Section / Content Link elements are output.

By default, if you output a Section/Content Link element using the publish Helper a full link will be output.

Using the example of an element called "Event Link":

{{{publish element="Event Link"}}}

You may need to access just the link URL or just the link text.

This is where the link Helper can help.

The link Helper is our first example of a "block level" helper. That means it has an opening and closing expression and content can be output in between.

It's used like:

{{#link element="Event Link" }}
<p>The link URL is: {{linkUrl}}</p>
<p>The link Text is: {{linkText}}</p>
{{/link}}

The {{linkUrl}} and {{linkText}} expressions are only available when used inside the Block level link Helper.

list and selected Helpers

The list and selected Helpers are both used in order to help with the output of List elements:

Select Box
Check Box
Radio Button
Multi-select List
Multiple Select
Cascading List

The list and selected Helpers can't be used with the Keyword Selector element as that element accepts a mix of list items and plain text. You can use the publish Helper to output the value of a Keyword Selector element if required.

Both the list and selected Helpers are designed to be used alongside the built-in each block expression with handlebars.

Let's start with the list Helper:

{{#each (list element="List Content Element")}}
<p>{{name}} - {{value}}</p>
{{/each}}

The above code is looping over every element in the list whether it is selected by the user or not and outputting the name and value in paragraphs.

However, there are a lot more variables available to use than just {{name}} and {{value}}. With both the list and selected Helpers we have the following variables available to us:

listId - The Id of the list that this entry belongs to.
entryId - The Id of this list entry.
name - The name of this list entry.
value - The value of this list entry.
sequence - The sequence of this entry in the list.
language - The language of the list entry.
selected - true if the list entry is selected, false otherwise.
hasSubList - true if the entry contains a sub-list.
subList - A reference to the sub-list, if one is present.
subListId - the Id of the sub-list, if present.

In addition to the variables relating to each list entry returned, there are a number of variables made available to give the developer more information about the position of each entry in the list.

@first - true if this is the first entry in the list/array.
@last - true if this is the last entry in the list/array.
@odd - true if this this entry has an odd index. Note that the array is zero-indexed.
@even - true if this this entry has an even index. Note that the array is zero-indexed.
@index - Returns the index of this entry within the list/array.

These allow us full control over how the lists should be output.

In the following example we'll create a HTML unordered list (<ul>) containing all the values in the list, and the values the user has selected in the content type should be output in bold:

{{#each (list element="List Content Element")}}
{{#if @first}}
<ul>
{{/if}}

<li>{{#if selected}}<strong>{{/if}}{{name}}{{#if selected}}</strong>{{/if}}<li>

{{#if @last}}
</ul>
{{/if}}
{{/each}}

We make use of the if block expression to only output information if the parameter passed in is true. We'll deep dive into conditional logic a little later.

The selected Helper works exactly the same way and has the same variables available to us. The only difference is that while the list Helper allows you to loop over all items in the list (whether they're selected or not), the selected Helper will allow you to loop over just the list items a user has selected in the content.

dateElement Helper

If you were to output a Date element using the publish Helper like this:

You'd get an output in the following format.

Thu, 25 Apr 2024 09:00:05 UTC

This is where the dateElement Helper comes in. The dateElement Helper is used alongside the built-in dateFormat Helper in order to allow you to output Date elements in whatever format you need.

If I wanted to output a Date Element using a custom format I could do that like:

{{dateFormat (dateElement element="Date element") "YYYY/MM/dd hh:mma" }}

Which would output something like:

2024/04/25 09:00AM

mediaId Helper

If you were to output a Media element using the publish Helper like this:

{{{publish element="Media element"}}}

The media element would be output using the standard media layout selected in the UI.

If you needed to enforce a specific alternate Media layout you can pass the mediaID Helper into the media Helper as a subexpression to do so.

It would work like:

{{{media id=(mediaId element="Media element") layout="text/alternative"}}}

The mediaId Helper outputs the ID of the selected Media element and then passes it through to the media Helper to output with an alternate layout.

file Helper

The file Helper is used to output File elements.

It's used like this:

The equivalent T4 tag would be:

filesize Helper

The filesize Helper is used to output the size of the referenced Content Element. In the case of text elements, it outputs the length of the text returned by the publish method. For elements such as "File" it will output the size of the file.

It's used like:

Conditional Helpers

One of the most powerful things about handlebars is that you can apply conditional logic to change how things get output.

Below are some examples of how to work with these helpers.

ifSet Helper

The ifSet Block level Helper allows you to determine whether or not a content element has been set/used.

For example, you may decide to display different things depending on whether a Checkbox is checked, or when an element does or doesn't have a value.

It's used like:

{{#ifSet element="Title" }}
<h2>{{publish element="Title"}}</h2>
{{else}}
<h2>This is my fallback title</h2>
{{/ifSet}}

Note the use of the {{else}} expression – allowing us to determine what should be output if an element isn't set.

if and unless Helpers

Alongside the ifSet Helper for checking whether an element has been used, you also have access to the built-in if and unless handlebars helpers.

These can be used to check whether a value is true or false and then modify our output.

For example here's an if:

{{#if true }}
<h2>I will always be published because the condition is true</h2>
{{else}}
<h2>I will never be published because the condition is true</h2>
{{/if}}

Unless is the inverse behaviour of if. Here's an example of unless:

{{#unless true }}
<h2>I will never be published because the condition is true</h2>
{{else}}
<h2>I will always be published because the condition is true</h2>
{{/unless}}

Comparison operators

There are a number of helpers to allow you to compare values:

eq - Tests if two values are equal
neq - Tests if two values are not equal
gt - Tests if one value is greater than another
gte - Tests if one value is greater than or equal to another
lt - Tests if one value is less than another
lte - Tests if one value is less than or equal to another
and - Tests if both values are true
or - Tests if either values are true
not - If the provided value is false then the block will not be processed

This is a good time to talk about the syntax used for passing arguments/parameters to handlebar expressions as it may not be intuitive if you're used to how we pass parameters into functions in languages like Java, JavaScript, PHP, Python etc.

Arguments are space separated when passed to handlebars expressions (as opposed to comma separated).

So for example if I want to check if the number 5 is less than 8 I would do:

{{#lt 5 8}}
<p>5 is indeed less than 8</p>
{{else}}
<p>This will never be published because 5 is always less than 8</p>
{{/lt}}

This would be most useful when comparing data a user has input with expected data.

For example if we want to output information if a user enters the word "Hello" in a plain text element called "Greeting".

{{#eq (publish element="Greeting") "Hello"}}
<p>Hello to you too!</p>
{{else}}
<p>You didn't say "Hello".</p>
{{/eq}}

Asset Helpers

nav Helper

The nav helper is a simple helper that allows you to output a navigation object.

It's used like:

The equivalent T4 tag would be:

media Helper

The media helper is a simple helper that allows you to output an item from the media library.

It's used like:

{{{media id="123" layout="image/responsive"}}}

The equivalent T4 tag would be:

form Helper

The form helper is a simple helper that allows you to output a Form Builder form.

You can choose to output the form with or without an iframe.

It's used like:

{{{form id="123" name="My form"}}}

{{{form id="123" name="My form" use-iframe="true"}}}

The equivalent T4 tag would be:

meta Helper

The meta helper is a simple helper that will output defined meta tags.

It's used like:

The equivalent T4 tag would be:

Content Position Helpers

You may want to modify the format of content in a section depending on where that content is positioned in a section.

There are a number of block level helpers that will allow you to do this.

first Helper

The first Block level helper will be true when the content item is the first piece of content in a section.

Used like:

{{#first}}
<h1>First content item in the section</h1>
{{/first}}

last Helper

The last Block level helper will be true when the content item is the first piece of content in a section.

Used like:

{{#last}}
<footer>Last content item in the section</footer>
{{/last}}

firstOfType Helper

The firstOfType Block level helper will be true when the content item is the first piece of content using this Content Type in a section.

Used like:

{{#firstOfType}}
<h2>First instance of this content type used in the section</h2>
{{/firstOfType}}

lastOfType Helper

The lastOfType Block level helper will be true when the content item is the last piece of content using this Content Type in a section.

Used like:

{{#lastOfType}}
<h2>Last instance of this content type used in the section</h2>
{{/lastOfType}}

firstInSequence Helper

The firstInSequence Block level helper will be true when the content item is the first piece of content using this Content Type in an uninterrupted sequence of content in a section.

Used like:

{{#firstInSequence}}
<section class="wrapper">
<h2>First in a sequence of Slide content so a section tag is opened (but not closed)</h2>
{{/firstInSequence}}

By default firstInSequence considers single instances of items as being in a sequence (of one). If you need this to be considered false you can pass the optional parameter match-single="false" like so:

{{#firstInSequence match-single="false"}}
This will not be output if the content before and after this content item use a different Content type.
{{/firstInSequence}}

lastInSequence Helper

The lastInSequence Block level helper will be true when the content item is the last piece of content using this Content Type in an uninterrupted sequence of content in a section.

Used like:

{{#lastInSequence}}
<p>Last in a sequence of content of this content type in a section so a section tag is closed</p>
</section>
{{/lastInSequence}}

By default lastInSequence considers single instances of items as being in a sequence (of one). If you need this to be considered false you can pass the optional parameter match-single="false" like so:

{{#lastInSequence match-single="false"}}
This will not be output if the content before and after this content item use a different Content type.
{{/lastInSequence}}

Summary of position helpers

Consider this section with 8 instances of content:

An example of 8 content items in a section

there is:

1 "general content"
3 "wrapper item"s
1 "general content"
3 more "wrapper items"

This is the resulting logic table:

Order	Content Type	first	last	firstOfType	lastOfType	firstInSequence	lastInSequence
1	General Content	✅	❌	✅	❌	✅	✅
2	Wrapper Item	❌	❌	✅	❌	✅	❌
3	Wrapper Item	❌	❌	❌	❌	❌	❌
4	Wrapper Item	❌	❌	❌	❌	❌	✅
5	General Content	❌	❌	❌	✅	✅	✅
6	Wrapper Item	❌	❌	❌	❌	✅	❌
7	Wrapper Item	❌	❌	❌	❌	❌	❌
8	Wrapper Item	❌	✅	❌	✅	❌	✅

Preview and Fulltext Helpers

preview Helper

The preview Block level helper is used to determine whether or not the page is currently being previewed or not.

It's used like:

{{#preview}}
<p>This will only get output when the page is previewed</p>
{{else}}
<p>This will only get output on publish</p>
{{/preview}}

fulltext Helper

The fulltext Helper has both an inline and block level variant. It behaves differently depending on which is used.

The inline fulltext Helper can be used to output a link to the fulltext page of a given content type.

It's used like:

{{{fulltext linkText="Keep reading"}}}

This would have the same output as this equivalent t4 tag based layout:

<a href="<t4 type="content" name="Name" output="fulltext" />">Keep reading</a>

When used as a Block level element the fulltext helper can be used in a Page Layout and will let you know if the current page is a fulltext page or not.

For example:

{{#fulltext}}
<p>This is a fulltext page</p>
{{else}}
<p>This is not a fulltext page</p>
{{/fulltext}}

A great benefit of the fulltext Block helper in Page Layouts means that you can output content elements from a page layout. This is something that isn't possible with T4 tags but makes for some pretty interesting use cases.

For example – create a custom title element using the "Title" element of a content type if on a fulltext page.
The following example could be put into a Page Layout:

{{#fulltext}}
<title>{{sectionName}}: {{publish element="Title"}} - Terminalfour University</title>
{{else}}
<title>{{sectionName}} - Terminalfour University</title>
{{/fulltext}}

Alternate layout helpers

embed Helper

The embed helper is used to embed an alternate content layout from the current Content Type. This can be really useful if you want to have variations on a template or want to display content in different ways depending on conditions.

It's also useful for keeping Content layout code clean, organised and isolated.

It's used like:

It doesn't matter if what the processor type is of the layout you're embedding. So whether it's a standard T4 tag layout, a Handlebars layout, or even a Programmable layout you can use the snippet helper to include it.

snippet Helper

It's quite common to use the SectionMetaDescription Content type to create layouts for code or information that you want to be available in every section.

This is often used alongside a Related Content navigation object that looks in the current section for content with an alternate layout.

With the snippet Helper you can now pull in a layout from the SectionMetaDescription Content type without the need to create any navigation objects.

Used like:

It doesn't matter if what the processor type is of the layout you're including with the snippet Helper. So whether it's a standard T4 tag layout, a Handlebars layout, or even a Programmable layout you can use the snippet helper to include it.

Miscellaneous Content Helpers

There are a number of miscellaneous Helpers to output information about a piece of content.

contentId Helper

Used to output the content Id of the content it's used in.

Used like:

contentVersion Helper

Used to output the content version of the content it's used in.

Used like:

anchor Helper

Used to output a span tag with an id for the specific content item. Used so you can link to specific pieces of content and it will scroll them in to view.

Used like:

Content Date Helpers

There are a number of Helpers to output dates associated with content items.

The following helpers can all be used in conjunction with the dateFormat Helper in order to format the date as you like.

// e.g. {{dateFormat (dateToFormat) "formatString"}}
{{dateFormat (publishDate) "YYYY/MM/dd"}}

The date format string can contain values as outlined in the format Dates section of the documentation.

publishDate Helper

Used to output the publish date of content if it is set (if it isn't set this returns an empty value).

Used like:

expiryDate Helper

Used to output the expiry date of content if it is set (if it isn't set this returns an empty value).

Used like:

contentLastModifiedDate Helper

Used to output the last modified date of the current content (if there's no currently publishing version of the content this will return an empty value).

Used like:

createDate Helper

Used to output the last modified date the content was first created.

Used like:

Miscellaneous Page URL Helpers

There are a number of miscellaneous Helpers to provide you with information about the URL of the page being viewed (whether it's a fulltext page, or a standard index page).

The following URL Helpers all rely on the Channel settings including a "Channel publish URL" value. If this field is blank in your channel settings these helpers cannot output the published page URLs.

pageURL Helper

Used to output the current page URL. In preview this will output the Preview URL, and in publish it will output the published URL.

Used like:

publishURL Helper

Used to output the current page's publish URL. In preview and in publish it will output the published URL.

Used like:

previewURL Helper

Used to output the current page's preview URL. In preview and in publish it will output the preview URL.

Used like:

canonicalURL Helper

Used to output the current page's canonical URL. Generally this is used to output a <link> tag in the header of a Page Layout so that if a section is mirrored, the canonicalURL will always return the original URL.

Used like:

Miscellaneous Section and Channel Helpers

section Helper

The section helper can be used to output an element from the SectionMetaDescription content type.

It's used like:

sectionId Helper

Used to output the ID of the current section.

It's used like:

sectionName Helper

Used to output the name of the current section.

It's used like:

channelId Helper

Used to output the current Channel's ID.

It's used like:

channelName Helper

Used to output the Name of the current Channel.

Used like:

channelDescription Helper

Used to output the Description of the current Channel.

Used like:

Miscellaneous CMS Links helper

directEditSection Helper

Used to output a link to Direct Edit a section.

Used like:

{{{directEditSection}}}

editSection Helper

Used to output a link to edit this section in the standard Terminalfour interface

Used like:

{{{editSection}}}

createSection Helper

Used to create a link that will create a subsection of the current section in the standard Terminalfour interface.

Used like:

{{{createSection}}}

editContent Helper

Used to create a link to edit the current content item within the standard Terminalfour interface.

Used like:

{{{editContent}}}

createContent Helper

Used to create a link that will create content within the current section in the standard Terminalfour interface.

Used like:

{{{createContent}}}

String Manipulation Helpers

The following Helpers allow you to modify Strings before they are output to the page.

abbreviate

The abbreviate Helper is used to truncate a string to the provided number of characters. If a string is smaller than the provided number it is not changed. Otherwise an ellipses (...) is appended to the abbreviated string.

It's used like: