Templating with Handlebars

1. Overview

In this tutorial, we’ll look into the Handlebars.java library for easy template management.

2. Maven Dependencies

Let’s start with adding the handlebars dependency:

<dependency>
    <groupId>com.github.jknack</groupId>
    <artifactId>handlebars</artifactId>
    <version>4.3.1</version>
</dependency>

3. A Simple Template

A Handlebars template can be any kind of text file. It consists of tags like {{name}} and {{#each people}}.

Then we fill in these tags by passing a context object, like a Map or other Object.

3.1. Using this

To pass a single String value to our template, we can use any Object as the context. We must also use the {{this}} tag in our template.

Then Handlebars calls the toString method on the context object and replaces the tag with the result:

@Test
public void whenThereIsNoTemplateFile_ThenCompilesInline() throws IOException {
    Handlebars handlebars = new Handlebars();
    Template template = handlebars.compileInline("Hi {{this}}!");
    
    String templateString = template.apply("Baeldung");
    
    assertThat(templateString).isEqualTo("Hi Baeldung!");
}

In the above example, we first create an instance of Handlebars, our API entry point.

Then, we give that instance our template. Here, we just pass the template inline, but we’ll see in a moment some more powerful ways.

Finally, we give the compiled template our context. {{this}} is just going to end up calling toString, which is why we see “Hi Baeldung!”.

3.2. Passing a Map as Context Object

We just saw how to send a String for our context, now let’s try a Map:

@Test
public void whenParameterMapIsSupplied_thenDisplays() throws IOException {
    Handlebars handlebars = new Handlebars();
    Template template = handlebars.compileInline("Hi {{name}}!");
    Map<String, String> parameterMap = new HashMap<>();
    parameterMap.put("name", "Baeldung");
    
    String templateString = template.apply(parameterMap);
    
    assertThat(templateString).isEqualTo("Hi Baeldung!");
}

Similar to the previous example, we’re compiling our template and then passing the context object, but this time as a Map.

Also, notice that we’re using {{name}} instead of {{this}}. This means that our map must contain the key, name.

3.3. Passing a Custom Object as Context Object

We can also pass a custom object to our template:

public class Person {
    private String name;
    private boolean busy;
    private Address address = new Address();
    private List<Person> friends = new ArrayList<>();
 
    public static class Address {
        private String street;       
    }
}

Using the Person class, we’ll achieve the same result as the previous example:

@Test
public void whenParameterObjectIsSupplied_ThenDisplays() throws IOException {
    Handlebars handlebars = new Handlebars();
    Template template = handlebars.compileInline("Hi {{name}}!");
    Person person = new Person();
    person.setName("Baeldung");
    
    String templateString = template.apply(person);
    
    assertThat(templateString).isEqualTo("Hi Baeldung!");
}

{{name}} in our template will drill into our Person object and get the value of the name field.

4. Template Loaders

So far, we’ve used templates that are defined inside the code. However, it is not the only option. We can also read templates from text files.

Handlebars.java provides special support for reading templates from the classpath, filesystem or servlet context. By default, Handlebars scans the classpath to load the given template:

@Test
public void whenNoLoaderIsGiven_ThenSearchesClasspath() throws IOException {
    Handlebars handlebars = new Handlebars();
    Template template = handlebars.compile("greeting");
    Person person = getPerson("Baeldung");
    
    String templateString = template.apply(person);
    
    assertThat(templateString).isEqualTo("Hi Baeldung!");
}

So, because we called compile instead of compileInline, this is a hint to Handlebars to look for /greeting.hbs on the classpath.

However, we can also configure these properties with ClassPathTemplateLoader:

@Test
public void whenClasspathTemplateLoaderIsGiven_ThenSearchesClasspathWithPrefixSuffix() throws IOException {
    TemplateLoader loader = new ClassPathTemplateLoader("/handlebars", ".html");
    Handlebars handlebars = new Handlebars(loader);
    Template template = handlebars.compile("greeting");
    // ... same as before
}

In this case, we’re telling Handlebars to look for the /handlebars/greeting.html on the classpath.

Finally, we can chain multiple TemplateLoader instances:

@Test
public void whenMultipleLoadersAreGiven_ThenSearchesSequentially() throws IOException {
    TemplateLoader firstLoader = new ClassPathTemplateLoader("/handlebars", ".html");
    TemplateLoader secondLoader = new ClassPathTemplateLoader("/templates", ".html");
    Handlebars handlebars = new Handlebars().with(firstLoader, secondLoader);
    // ... same as before
}

So, here, we’ve got two loaders, and that means Handlebars will search two directories for the greeting template.

5. Built-in Helpers

Built-in helpers provide us additional functionality when writing our templates.

5.1. with Helper

The with helper changes the current context:

{{#with address}}
<h4>I live in {{street}}</h4>
{{/with}}

In our sample template, the {{#with address}} tag starts the section and the {{/with}} tag ends it.

In essence, we’re drilling into the current context object – let’s say person – and setting address as the local context for the with section. Thereafter, every field reference in this section will be prepended by person.address.

So, the {{street}} tag will hold the value of person.address.street:

@Test
public void whenUsedWith_ThenContextChanges() throws IOException {
    Handlebars handlebars = new Handlebars(templateLoader);
    Template template = handlebars.compile("with");
    Person person = getPerson("Baeldung");
    person.getAddress().setStreet("World");
    
    String templateString = template.apply(person);
    
    assertThat(templateString).contains("<h4>I live in World</h4>");
}

We’re compiling our template and assigning a Person instance as the context object. Notice that the Person class has an Address field. This is the field we’re supplying to the with helper.

Though we went one level into our context object, it is perfectly fine to go deeper if the context object has several nested levels.

5.2. each Helper

The each helper iterates over a collection:

{{#each friends}}
<span>{{name}} is my friend.</span>
{{/each}}

As a result of starting and closing the iteration section with {{#each friends}} and {{/each}} tags, Handlebars will iterate over the friends field of the context object.

@Test
public void whenUsedEach_ThenIterates() throws IOException {
    Handlebars handlebars = new Handlebars(templateLoader);
    Template template = handlebars.compile("each");
    Person person = getPerson("Baeldung");
    Person friend1 = getPerson("Java");
    Person friend2 = getPerson("Spring");
    person.getFriends().add(friend1);
    person.getFriends().add(friend2);
    
    String templateString = template.apply(person);
    
    assertThat(templateString)
      .contains("<span>Java is my friend.</span>", "<span>Spring is my friend.</span>");
}

In the example, we’re assigning two Person instances to the friends field of the context object. So, Handlebars repeats the HTML part two times in the final output.

5.3. if Helper

Lastly, the if helper provides conditional rendering.

{{#if busy}}
<h4>{{name}} is busy.</h4>
{{else}}
<h4>{{name}} is not busy.</h4>
{{/if}}

In our template, we’re providing different messages according to the busy field.

@Test
public void whenUsedIf_ThenPutsCondition() throws IOException {
    Handlebars handlebars = new Handlebars(templateLoader);
    Template template = handlebars.compile("if");
    Person person = getPerson("Baeldung");
    person.setBusy(true);
    
    String templateString = template.apply(person);
    
    assertThat(templateString).contains("<h4>Baeldung is busy.</h4>");
}

After compiling the template, we’re setting the context object. Since the busy field is true, the final output becomes <h4>Baeldung is busy.</h4>.

6. Custom Template Helpers

We can also create our own custom helpers.

6.1. Helper

The Helper interface enables us to create a template helper.

As the first step, we must provide an implementation of Helper:

new Helper<Person>() {
    @Override
    public Object apply(Person context, Options options) throws IOException {
        String busyString = context.isBusy() ? "busy" : "available";
        return context.getName() + " - " + busyString;
    }
}

As we can see, the Helper interface has only one method which accepts the context and options objects. For our purposes, we’ll output the name and busy fields of Person.

After creating the helper, we must also register our custom helper with Handlebars:

@Test
public void whenHelperIsCreated_ThenCanRegister() throws IOException {
    Handlebars handlebars = new Handlebars(templateLoader);
    handlebars.registerHelper("isBusy", new Helper<Person>() {
        @Override
        public Object apply(Person context, Options options) throws IOException {
            String busyString = context.isBusy() ? "busy" : "available";
            return context.getName() + " - " + busyString;
        }
    });
    
    // implementation details
}

In our example, we’re registering our helper under the name of isBusy using the Handlebars.registerHelper() method.

As the last step, we must define a tag in our template using the name of the helper:

{{#isBusy this}}{{/isBusy}}

Notice that each helper has a starting and ending tag.

6.2. Helper Methods

When we use the Helper interface, we can only create only one helper. In contrast, a helper source class enables us to define multiple template helpers.

Moreover, we don’t need to implement any specific interface. We just write our helper methods in a class then HandleBars extracts helper definitions using reflection:

public class HelperSource {

    public String isBusy(Person context) {
        String busyString = context.isBusy() ? "busy" : "available";
        return context.getName() + " - " + busyString;
    }

    // Other helper methods
}

Since a helper source can contain multiple helper implementations, registration is different than the single helper registration:

@Test
public void whenHelperSourceIsCreated_ThenCanRegister() throws IOException {
    Handlebars handlebars = new Handlebars(templateLoader);
    handlebars.registerHelpers(new HelperSource());
    
    // Implementation details
}

We’re registering our helpers using the Handlebars.registerHelpers() method. Moreover, the name of the helper method becomes the name of the helper tag.

7. Template Reuse

The Handlebars library provides several ways to reuse our existing templates.

7.1. Template Inclusion

Template inclusion is one of the approaches for reusing templates. It favors the composition of the templates.

<h4>Hi {{name}}!</h4>

This is the content of the header template – header.html.

In order to use it in another template, we must refer to the header template.

{{>header}}
<p>This is the page {{name}}</p>

We have the page template – page.html – which includes the header template using {{>header}}.

When Handlebars.java processes the template, the final output will also contain the contents of header:

@Test
public void whenOtherTemplateIsReferenced_ThenCanReuse() throws IOException {
    Handlebars handlebars = new Handlebars(templateLoader);
    Template template = handlebars.compile("page");
    Person person = new Person();
    person.setName("Baeldung");
    
    String templateString = template.apply(person);
    
    assertThat(templateString)
      .contains("<h4>Hi Baeldung!</h4>", "<p>This is the page Baeldung</p>");
}

7.2. Template Inheritance

Alternatively to composition, Handlebars provides the template inheritance.

We can achieve inheritance relationships using the {{#block}} and {{#partial}} tags:

<html>
<body>
{{#block "intro"}}
  This is the intro
{{/block}}
{{#block "message"}}
{{/block}}
</body>
</html>

By doing so, the messagebase template has two blocks – intro and message.

To apply inheritance, we need to override these blocks in other templates using {{#partial}}:

{{#partial "message" }}
  Hi there!
{{/partial}}
{{> messagebase}}

This is the simplemessage template. Notice that we’re including the messagebase template and also overriding the message block.

8. Summary

In this tutorial, we’ve looked at Handlebars.java to create and manage templates.

We started with the basic tag usage and then looked at the different options to load the Handlebars templates.

We also investigated the template helpers which provide a great deal of functionality. Lastly, we looked at the different ways to reuse our templates.