Handlebars.java
===============

Logic-less and semantic Mustache templates with Java

Handlebars handlebars = new Handlebars();

Template template = handlebars.compileInline("Hello {{this}}!");

System.out.println(template.apply("Handlebars.java"));

Output:

Hello Handlebars.java!

Handlebars.java is a Java port of handlebars.

Handlebars provides the power necessary to let you build semantic templates effectively with no frustration.

Mustache templates are compatible with Handlebars, so you can take a Mustache template, import it into Handlebars, and start taking advantage of the extra Handlebars features.

Requirements

• Handlebars 4.4+ requires Java 17 or higher.
• Handlebars 4.3+ requires Java 8 or higher (NOT MAINTAINED).

Getting Started

In general, the syntax of Handlebars templates is a superset of Mustache templates. For basic syntax, check out the Mustache manpage.

The Handlebars.java blog is a good place for getting started too. Javadoc is available at javadoc.io.

Maven

Stable version: 

  <dependency>
    <groupId>com.github.jknack</groupId>
    <artifactId>handlebars</artifactId>
    <version>${handlebars-version}</version>
  </dependency>

Loading templates

Templates are loaded using the ``TemplateLoader` class. Handlebars.java provides three implementations of a ``TemplateLoader

 * ClassPathTemplateLoader (default)
 * FileTemplateLoader
 * SpringTemplateLoader (see the [handlebars-springmvc](https://github.com/jknack/handlebars.java/tree/master/handlebars-springmvc) module)

This example loads

mytemplate.hbs:

var template = handlebars.compile("mytemplate");

System.out.println(template.apply("Handlebars.java"));
```

Output:

Hello Handlebars.java!

You can specify a different ```TemplateLoader

#### Templates prefix and suffix
A

 *

 *

Example:

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

System.out.println(template.apply("Handlebars.java"));

Handlebars.java will resolve

## The Handlebars.java Server
The handlebars.java server is small application where you can write Mustache/Handlebars template and merge them with data.

It is a useful tool for Web Designers.

Download from Maven Central:

1. Go [here](http://search.maven.org/#search%7Cga%7C1%7Chandlebars-proto)
2. Under the **Download** section click on **jar**

Maven:

com.github.jknack
handlebars-proto
${current-version}

Usage:

Example:

**myTemplates/home.hbs**

{{#items}}
{{name}}
{{/items}}

**myTemplates/home.json**

or if you prefer YAML **myTemplates/home.yml**:

• name: Handlebars.java rocks!

### Open a browser a type:

enjoy it!


### Additional options:

* -dir: set the template directory
* -prefix: set the template's prefix, default is /
* -suffix: set the template's suffix, default is .hbs
* -context: set the context's path, default is /
* -port: set port number, default is 6780
* -content-type: set the content-type header, default is text/html

### Multiple data sources per template
Sometimes you need or want to test multiple datasets over a single template, you can do that by setting a

Example:

Please note you don't have to specify the extension file.

## Helpers

### Built-in helpers:
 * **with**
 * **each**
 * **if**
 * **unless**
 * **log**
 * **block**
 * **partial**
 * **precompile**
 * **embedded**
 * **i18n** and **i18nJs** 
 * **string helpers**
 * **conditional helpers**

### with, each, if, unless:
 See the [built-in helper documentation](https://handlebarsjs.com/guide/block-helpers.html).

### block and partial
 Block and partial helpers work together to provide you [Template Inheritance](http://jknack.github.io/handlebars.java/reuse.html).

Usage:

context: A string literal which defines the region's name.

Usage:

context: A string literal which defines the region's name.

### precompile
 Precompile a Handlebars.java template to JavaScript using handlebars.js

user.hbs

home.hbs

{{precompile "user"}}

Output:

(function() {
var template = Handlebars.template, templates = Handlebars.templates = Handlebars.templates || {};
templates['user'] = template(function (Handlebars,depth0,helpers,partials,data) {
helpers = helpers || Handlebars.helpers;
var buffer = "", functionType="function", escapeExpression=this.escapeExpression;

buffer += "Hi ";
depth0 = typeof depth0 === functionType ? depth0() : depth0;
buffer += escapeExpression(depth0) + "!";
return buffer;});
})();

You can access the precompiled template with:

By default it uses:

For more information have a look at the [Precompiling Templates](https://github.com/wycats/handlebars.js/) documentation. 

Usage:

context: A template name. Required.

wrapper: One of "anonymous", "amd" or "none". Default is: "anonymous" 

There is a [maven plugin](https://github.com/jknack/handlebars.java/tree/master/handlebars-maven-plugin) available too.

### embedded
 The embedded helper allow you to "embedded" a handlebars template inside a

user.hbs

home.hbs

...
{{embedded "user"}}
...

Output:

...

{{firstName}}
{{lastName}}

...

Usage:

context: A template name. Required.

### i18n
 A helper built on top of a {@link ResourceBundle}. A {@link ResourceBundle} is the most well known mechanism for internationalization (i18n) in Java.

Usage:

This require a

Using a locale:

This requires a

Using a different bundle:

This requires a

Using a message format:

Where

### i18nJs
 Translate a

Usage:

If the locale argument is present it will translate that locale to JavaScript. Otherwise, it will use the default locale.

The generated code looks like this:

I18n.defaultLocale = 'es_AR';
I18n.locale = 'es_AR';
I18n.translations = I18n.translations || {};
// Spanish (Argentina)
I18n.translations['es_AR'] = {
"hello": "Hi {{arg0}}!"
}

Finally, it converts message patterns like:

### string helpers
 Functions like abbreviate, capitalize, join, dateFormat, yesno, etc., are available from [StringHelpers](https://github.com/jknack/handlebars.java/blob/master/handlebars/src/main/java/com/github/jknack/handlebars/helper/StringHelpers.java).
 
> NOTE: You need to register string helpers (they are not added by default)

### conditional helpers
 Functions like eq, neq, lt, gt, and, or, not, etc., are available from [ConditionalHelpers](https://github.com/jknack/handlebars.java/blob/master/handlebars/src/main/java/com/github/jknack/handlebars/helper/ConditionalHelpers.java).
 
> NOTE: You need to register conditional helpers (they are not added by default)

### TypeSafe Templates
 TypeSafe templates are created by extending the

// 1
public static interface UserTemplate extends TypeSafeTemplate {

// 2
public UserTemplate setAge(int age);

public UserTemplate setRole(String role);

}

// 3
UserTemplate userTmpl = handlebars.compileInline("{{name}} is {{age}} years old!")
.as(UserTemplate.class);

userTmpl.setAge(32);

assertEquals("Edgar is 32 years old!", userTmpl.apply(new User("Edgar")));

 1. You extend the

 2. You add all the set method you need. The set method can returns

 3. You create a new type safe template using the:

### Registering Helpers

There are two ways of registering helpers.

#### Using the

";
for (Blog blog: list) {
ret += "
• " + options.fn(blog) + "
";
}
return new Handlebars.SafeString(ret + "

#### Using a

A helper source is any class with public methods returning an instance of a

Where: 

* A method can/can't be static
* The method's name becomes the helper's name
* Context, parameters and options are all optionals
* If context and options are present they must be the **first** and **last** arguments of the method

All these are valid definitions of helper methods:

public static String now() {
return new Date().toString();
}

public String render(Blog context, String param0, int param1, boolean param2, Options options) {
return ...
}
}

...

handlebars.registerHelpers(new HelperSource());

Or, if you prefer static methods only:

#### With plain

That's right since

helpers.js:

Cool, isn't?


### Helper Options

#### Parameters

Bean bean = new Bean();
bean.setParam1(123);

Template template = handlebars.compileInline("{{#blog-list blogs "param0" param1}}{{/blog-list}}");
template.apply(bean);

#### Default parameters

Template template = handlebars.compileInline("{{#blog-list blogs}}{{/blog-list}}");

#### Hash

handlebars.compileInline("{{#blog-list blogs class="blog-css"}}{{/blog-list}}");

#### Default hash

handlebars.compileInline("{{#blog-list blogs}}{{/blog-list}}");

## Error reporting

### Syntax errors

Examples:

template.hbs

If a partial isn't found or if it has errors, a call stack is added:

### Helper/Runtime errors
Helper or runtime errors are similar to syntax errors, except for two things:

1. The location of the problem may (or may not) be the correct one
2. The stack-trace isn't available

Examples:

Block helper:

base.hbs

{{#block}} {{/block}}

Handlebars.java reports:

In short, from a helper you can throw an Exception and Handlebars.java will add the filename, line, column and the evidence.

## Advanced Usage

### Extending the context stack
 Let's say you need to access to the current logged-in user in every single view/page.
 You can publish the current logged in user by hooking into the context-stack. See it in action:

 Where is the

### Using the ValueResolver
 By default, Handlebars.java use the JavaBean methods (i.e. public getXxx and isXxx methods), Map as value and Method as value resolvers.
 
 You can choose a different value resolver. This section describe how to do this.
 
#### The JavaBeanValueResolver
 Resolves values from public methods prefixed with "get/is"

#### The FieldValueResolver
 Resolves values from no-static fields.

#### The MapValueResolver
 Resolves values from a

#### The MethodValueResolver
 Resolves values from public methods.

#### The JsonNodeValueResolver
 Resolves values from

Available in [Jackson 1.x](https://github.com/jknack/handlebars.java/tree/master/handlebars-json) and [Jackson 2.x](https://github.com/jknack/handlebars.java/tree/master/handlebars-jackson2) modules.

#### Using multiples value resolvers

### The Cache System
 The cache system is designed to provide scalability and flexibility. Here is a quick view of the

/**

• Remove all mappings from the cache.

*/
void clear();

/**

• Evict the mapping for this source from this cache if it is present.

*

• @param source the source whose mapping is to be removed from the cache

*/
void evict(TemplateSource source);

/**

• Return the value to which this cache maps the specified key.

*

• @param source source whose associated template is to be returned.
• @param parser The Handlebars parser.
• @return A template.
• @throws IOException If input can't be parsed.

*/
Template get(TemplateSource source, Parser parser) throws IOException;
}

As you can see, there isn't a

By default, Handlebars.java uses a

In addition to the

1.

This implementation works very well in general, but there is a small window where two or more threads can compile the same template. This isn't a huge problem with Handlebars.java because the compiler is very very fast.
But if for some reason you don't want this, you can use the

2.

This cache implementation eliminates the window created by

It follows the patterns described in [Java Concurrency in Practice](http://www.amazon.com/Java-Concurrency-Practice-Brian-Goetz/dp/0321349601) and ensures that a template will be compiled just once regardless of the number of threads.


3.

You can configure Handlebars.java to use a cache by:

### Using a MissingValueResolver (@deprecated)
NOTE: MissingValueResolver is available in

 A

### Helper Missing
 By default, Handlebars.java throws an

 You can override the default behaviour by providing a special helper:

### String form parameters
 You can access a parameter name if you set the: