Thursday, March 24, 2016

Handlebars. Module

Handlebars engine is a tread-safe, so I can initialize it only once and then compile templates using the single instance (with a cache system). So I moved all the handlebars code into the module. There were a few changes: configuration has been extracted to the handlebars.conf, handlebars cache has been used, MessagesApi now injecting into the helpers, so they are not static, and result type of the handlebars compilation is a play.twirl.api.Content.

Now I can easely inject HandlebarsApi in any component:

private HandlebarsApi handlebarsApi;

And compile the template just with one line

Content page = handlebarsApi.html("page", data);


First of all, I extracted the configuration. I like the include statement, so I easily created the handlebars settings.


# configure Handlebars API
    include "handlebars.conf"

handlebars.conf in the same directory as the application.conf

directory: "/templates"
extension: ".hbs"

In the code I can read handlebars properties as easy as



The creation of module in Play is simple.

Create a class. I used @Singleton because I want to initialize handlebars only ones and utilize the cache system.

package handlebars;

public class HandlebarsApi {

Extend the play.api.inject.Module class; bind your class.

package handlebars;

import play.api.Configuration;
import play.api.Environment;
import play.api.inject.Binding;
import scala.collection.Seq;

public class Module extends play.api.inject.Module {

  public Seq<Binding<?>> bindings(final Environment environment, final Configuration configuration) {
    return seq(bind(HandlebarsApi.class).toSelf());


The last step - enable the module in the application.conf

# Bind Handlebars API
play.modules.enabled += "handlebars.Module"


Handlebars has a good cache system. There is no need to build your own. I selected the Guava cache.

Add dependency to the build.sbt

libraryDependencies += "com.github.jknack" % "handlebars-guava-cache" % "4.0.4"

Initialize handlebars with the cache


import java.util.concurrent.TimeUnit;



// Initialize the cache. Could be builded from configuration as well
// For example: CacheBuilder.from(config.getString("hbs.cache")).build()
final Cache cache = CacheBuilder.newBuilder()
    .expireAfterWrite(10, TimeUnit.MINUTES)

// Initialize the engine with the cache
handlebars = new Handlebars(loader)
    .with(new GuavaTemplateCache(cache));



I use MessagesApi in the handlebars helper. Helpers are registering only once a time, fortunately MessagesApi is a singleton, so I put it in to the Helper's constructor.

Part of the Helpers class.

public final class Helpers {

  final MessagesApi messagesApi;

  public Helpers(final MessagesApi messagesApi){
    this.messagesApi = messagesApi;


  public CharSequence message(final String key, final Options options) {
    // Get the current language.
    final Lang lang = Context.current().lang();
    // Retrieve the message, internally formatted by MessageFormat.
    return messagesApi.get(lang, key, options.params);


Initialization of the Handlebars with the Helpers class.


public HandlebarsApi(... final MessagesApi messagesApi) {
  // Add helpers. MessagesApi is a singleton so we can use it in the helpers.
  Helpers helpers = new Helpers(messagesApi);




Trivial result of the template processing in the Play is the object of play.twirl.api.Content type. So I created a simple implementation of this class for the HTML template.

HTML Content wrapper:

package handlebars;

import play.twirl.api.Content;

class HtmlContent implements Content {

  private String body;
  HtmlContent(final String body){
    this.body = body;
  public String body() {
    return body;

  public String contentType() {
    return "text/html";


Wrapping the handlebars result:

public String render(final String templateName, final Object data) throws Exception {
  return handlebars

public Content html(final String templateName, final Object data) throws Exception {
  return new HtmlContent(render(templateName, data));

Mocking the Http.Context

In the process of testing templates I spend a little time to beat the nasty error
java.lang.RuntimeException: There is no HTTP Context available from here.
So do not forget to mockup the Http.Context. It's easy to do.

Here is an example from the project:

// Initialize application
Application application = new GuiceApplicationBuilder().build();

// Setup an HTTP Context
Http.Context context = mock(Http.Context.class);

// Setup the language and messages
Lang langRequest = Lang.forCode(requestLang);
Lang langSession = Lang.forCode(sessionLang);
MessagesApi messagesApi = application.injector().instanceOf(MessagesApi.class);
Messages messages = new Messages(langRequest, messagesApi);

// Train the Context

// Get the handlebars API
HandlebarsApi handlebarsApi = application.injector().instanceOf(HandlebarsApi.class);

Project on the Github

You can find this simple project with the Handlebars module on the github:

No comments:

Post a Comment