Handlebars.java

Logic-less and semantic templates with Java

by Edgar Espina Theme by mattgraham

Where is my {{ Mustache }} template?

In this section you will learn how to load Mustache templates from the file system, classpath, web context and more.

The template loader

Template are loaded using the TemplateLoader API, which looks as follows:

public interface TemplateLoader {

  String DEFAULT_PREFIX = "/";

  String DEFAULT_SUFFIX = ".hbs";

  String getPrefix();

  String getSuffix();

  TemplateSource sourceAt(final String location) throws IOException;

  String resolve(final String location);
}

Prefix and Suffix

These two properties control theabsolute pathof a template.

prefix: gets prepended to template names before being resolved.
suffix: gets appended to template names before being resolved. Default is: .hbs

For example, a templatehellowithprefix=/siteandsuffix=.htmlget resolved to/site/hello.html

Template template = handlebars.compile("hello");

The exactly same rules applies forpartials

{{> hello}}

You don't need to addprefix(like a home directory) andsuffix(like a file extension), theTemplateLoaderdoes it for you.

The default value ofprefixdepends on a specific implementation ofTemplateLoader.

The default value ofsuffixis .hbs, but as you saw before, you can change to.htmlor whatever make more sense to you (null included).

The template source

A template source is a lightweight reference to a physical template stored somewhere. The TemplateSource class, looks as follows:

public interface TemplateSource {
  String content() throws IOException;

  Reader reader() throws IOException;

  String filename();

  long lastModified();
}

You don't have to implement any of these classes, Handlebars.java does it for you. But if you want to store your templates in a database (for example), these are the two classes you need to implement.

The classpath template loader

The ClassPathTemplateLoader is the default template loader in Handlebars.java. If you don't set a template loader, Handlebars.java assume your templates are in the classpath.

For example:

The default prefix is/(a.k.a root of classpath) and the default suffix is.hbs(i.e. file extension is .hbs).

Handlebars handlebars = new Handlebars();
handlebars.compile("hello"); // resolved to: /hello.hbs

Setting prefix to theroot of classpathand.htmlas file extension.

TemplateLoader loader = new ClassPathTemplateLoader("/", ".html");
Handlebars handlebars = new Handlebars(loader);
handlebars.compile("hello"); // resolved to: /hello.html

Setting prefix to the/templatesand.htmlas file extension.

TemplateLoader loader = new ClassPathTemplateLoader("/templates", ".html");
Handlebars handlebars = new Handlebars(loader);
handlebars.compile("hello"); // resolved to: /templates/hello.html

The file template loader

The FileTemplateLoader load templates from a file system location. This template loader is useful if you need to make change to your templates after a deploy.

For example:

Setting prefix to the/usr/share/templatesand.htmlas file extension.

TemplateLoader loader = new FileTemplateLoader("/usr/share/templates",
  ".html");
Handlebars handlebars = new Handlebars(loader);
handlebars.compile("hello"); // resolved to: /usr/share/templates/hello.html

The servlet context template loader

The ServletContextTemplateLoader load templates from a JavaEE Web Context.

For example:

Setting prefix to theroot of the web contextand.hbsas file extension.

ServletContext servletContext = ...;
TemplateLoader loader = new ServletContextTemplateLoader(servletContext);
Handlebars handlebars = new Handlebars(loader);
handlebars.compile("hello"); // resolved to: /hello.hbs

Setting prefix to/and.htmlas file extension.

ServletContext servletContext = ...;
TemplateLoader loader = new ServletContextTemplateLoader(servletContext, "/",
  ".html");
Handlebars handlebars = new Handlebars(loader);
handlebars.compile("hello"); // resolved to: /hello.html

Setting prefix to/WEB-INF/pagesand.htmlas file extension.

ServletContext servletContext = ...;
TemplateLoader loader = new ServletContextTemplateLoader(servletContext,
  "/WEB-INF/pages", ".html");
Handlebars handlebars = new Handlebars(loader);
handlebars.compile("hello"); // resolved to: /WEB-INF/pages/hello.html

The composite template loader

The CompositeTemplateLoader let you combine two or more template loaders and makes possible multiples templates location for your application.

For example:

Using ClassPathTemplateLoader loader within a FileTemplateLoader:

ClassPathTemplateLoader cploader = ...;
FileTemplateLoader fsloader = ...;
Handlebars handlebars = new Handlebars().with(cploader, fsloader);
handlebars.compile("hello");

Loaders are executed in the order they are provided, so the first TemplateLoader that is able to resolved a template win.

Conclusion

TheTemplateLoaderandTemplateSourceare two key abstractions in Handlebars.java, they both work together for simplify the storage and resolution of templates.

Want to contribute?

Fork the project on Github.
Create an issue or fix one from the issues list.
Share your ideas or ask questions on mailing list - don't hesitate to write a reply - that helps us improve javadocs/FAQ.
If you miss a particular feature - browse or ask on the mailing list - don't hesitate to write a reply, show us a sample code and describe the problem.
Write a blog post about how you use or extend Handlebars.java.
Please suggest changes to javadoc/exception messages when you find something unclear.
If you have problems with documentation, find it non intuitive or hard to follow - let us know about it, we'll try to make it better according to your suggestions. Any constructive critique is greatly appreciated. Don't forget that this is an open source project developed and documented in spare time.

Thank you, for reading the Handlebars.java blog.