Handlebars - introduction
Publii uses Handlebars for theme creation. We have prepared a few predefined files which must be included in a basic theme. There are also a few additional files which can be added to a theme to achieve different layouts for a specific page like tags pages, authors pages, posts, pages, etc...
This article is an introduction to the most common Handlebars syntax elements which are necessary to create a theme in Publii.
How are Handlebars files rendered?
Handlebars are compiling *.hbs files and use context to render variables inside the template file.
A context is an object which contains data related to a current view.
It works in the following way: *.hbs file + context = final output
For example, if the context is an object like:
{
"message": "Hello World!"
}And the *.hbs file has the following structure:
<div>{{message}}</div>Then, we will receive as an output the following code:
<div>Hello World!</div>Code blocks and context
Context can be an object with nested values i.e.:
{
"message": {
"text1": "Lorem",
"text2": "Ipsum"
}
}In this case, we have to ways to access the data in the object:
1. Access the specific field directly:
<div>{{message.text1}}</div> 2. Access the specific filed using code blocks:
{{#message}}
<div>{{text1}}</div>
{{/message}}Code blocks are usually more useful as it creates a natural structure of the content in your *.hbs files. But sometimes you will need to access in the block a field which is one or more levels above the current level of nesting.
In this case, you have to use the ../ prefix. In the example, if we have the following context:
{
config: {
option1: "value1"
},
message: {
text1: "lorem"
}
} If we will use the code blocks method to access the nested fields variables and we will need to access config.option1 field, we will have to use a following syntax:
{{#message}}
<div>{{text1}}</div>
<div>{{../config.option1}}</div>
{{/message}} Conditional code blocks
Handlebars have two types of blocks - inline blocks and conditional blocks. Conditional blocks can have two outputs depending on the condition - if it is true or false.
The simplest example of the conditional code block is the if block:
{{#if field}}
Text displayed if field in context is true
{{else}}
Text displayed if field in context is false
{{/if}If you want to achieve a reversed behavior, you can use an unless conditional block:
{{#unless field}}
Text displayed if field in context is false
{{else}}
Text displayed if field in context is true
{{/unless} Of course, you can use a lot of more conditionals blocks. The main thing to remember is a fact that you should open it with the {{#NAME CONDITION}} syntax and close it with {{/NAME}} fragment.
Loops
You can iterate arrays and objects with the #each helper.
So if you have an array of arrays for each person in the project, you can use the following syntax:
{{#each persons}}
{{name}} - {{email}}
{{/each}}It can be used in the following context:
{
persons: [
{
name: "John",
email: "john@doe.com"
},
{
name: "Adam",
email: "adam@adam-and-eve.com"
}
]
}The #each helper will generate a list of all persons in a list.
Comments
You can put comments inside your *.hbs files which won't be rendered in the final HTML output. The syntax for comments in Handlebars is very simple:
{{! Your comment here !}}Custom elements
For Handlebars, you can define two custom elements:
Custom helpers can be used for simple operations and conditional blocks. They are usually used to do things that are impossible with available helpers.
You can use custom helpers for:
- Filtering content
- Add additional features (like blurred images for lazy-loading)
- Generate parametrized HTML output using a single line of code
Partials can be used for common parts of the themes. They are used to re-use the codebase. Thanks to partials, you can make changes to your theme in one place. That's why we highly recommend to use partials for reused theme parts - it will make theme maintenance much easier.
For example, Publii built-in themes partials can be used for:
- Page header,
- Page footer,
- Social sharing block,
- Pagination,
- Menu
Global variables
Some elements are common to all views and are used along with the normal context of the view.
It is called global variables - it is prefixed with an @ char. You can find a full list of these variables under global variables page. Each template file also has its own set of Handlebars tags.