Handlebars.java Helpers

Introduction

This library provides various Handlebars.java helpers

The source code is available on GitHub.

Getting Started

handlebars-java-helpers is available in Maven Central and JCenter.

Maven

<dependency>
    <groupId>org.beryx</groupId>
    <artifactId>handlebars-java-helpers</artifactId>
    <version>0.4.1</version>
</dependency>

Gradle

compile 'org.beryx:handlebars-java-helpers:0.4.1'

Helpers

def

Defines a Handlebars variable.

There are two ways of using def: as a basic or as a block helper.

Basic syntax: {{def 'varName' varValue}}
Block syntax: {{#def 'varName'}} varValue {{/def}}

Example:

YAML Model

user: jsmith
domain: example.com
offline: false

Template

{{def 'online' (not offline)}}
{{#def 'email'}}{{user}}@{{domain}}{{/def}}
Online: {{online}}
You can contact me at {{email}}.

Result

Online: true
You can contact me at jsmith@example.com.

ifb

Conditionally renders a block.

Syntax: {{#ifb condition}} text1 [{{else}} text2] {{/ifb}}

Unlike the built-in if helper, ifb tries to parse string conditions as boolean values. Moreover, if a string condition can be parsed as a number, its corresponding numerical value is evaluated as a boolean (0 is false, anything else is true). This is especially helpful when the condition is provided as a subexpression.

Example:

YAML Model

offline: false
value: 5

Template

if : online = {{#if (not offline)}}YES{{else}}NO{{/if}}
ifb: online = {{#ifb (not offline)}}YES{{else}}NO{{/ifb}}
if : {{value}} is an {{#if (math value '%' 2)}}odd{{else}}even{{/if}} number
ifb: {{value}} is an {{#ifb (math value '%' 2)}}odd{{else}}even{{/ifb}} number

Result

if : online = NO
ifb: online = YES
if : 5 is an even number
ifb: 5 is an odd number

default

Returns the first value, if it is defined and not empty, or the default value otherwise.

Syntax: {{default value defaultValue}}

Example:

YAML Model

bonus: 100

Template

bonus = {{default bonus 0}} points
penalty = {{default penalty 0}} points

Result

bonus = 100 points
penalty = 0 points

length

Returns the number of elements in a collection.

Syntax: {{length list}}

Example:

YAML Model

developers:
  - name: Alice
  - name: Brenda
  - name: Colin

Template

Team size: {{length developers}} developers

Result

Team size: 3 developers

math

Computes the result of an arithmetic operation.

Syntax: {{math operand1 'operator' operand2 [decimals=dec [locale=loc]]}}

Supported operators: +, -, *, /, %, **.

Example:

YAML Model

amount: 1500
bonus: 100
penalty: 30

Template

Your score: {{math (math amount '+' bonus) '-' penalty}} points

Result

Your score: 1570 points

You can customize the format of the result by specifying the number of decimals and the locale.

Example:

YAML Model

amount: 250
rate: 0.15

Template

interest: {{math amount '*' rate decimals=2 locale='de'}} EUR

Result

interest: 37,50 EUR

compare

Compares two operands using the specified relational operator.

Syntax: {{compare operand1 'operator' operand2 [asString=strBool]}}

Supported relational operators: ==, !=, <, <=, >, >=.

Example:

YAML Model

bonus: 100
penalty: 30

Template

Exceeded allowed penalty: {{compare penalty '>=' 50}}
{{#ifb (compare bonus '>' penalty)}}
You won!
{{else}}
Game over
{{/ifb}}

Result

Exceeded allowed penalty: false
You won!

If the operands are numeric you can enforce comparing them as strings by specifying asString=true.

asBoolean

Returns the boolean value of the operand.

Syntax: {{asBoolean value}}

Example:

YAML Model

middleName: Maria
debt: 0
credit: 5

Template

Has nickname: {{asBoolean nickname}}
Has middle name: {{asBoolean middleName}}
Has debt: {{asBoolean debt}}
Has credit: {{asBoolean credit}}

Result

Has nickname: false
Has middle name: true
Has debt: false
Has credit: true

not

Returns the negated value of the operand.

Syntax: {{not value}}

Example:

YAML Model

offline: false

Template

Online: {{not offline}}
{{#ifb (not offline)}}
Invite a friend to play with you!
{{else}}
Single-player mode.
{{/ifb}}

Result

Online: true
Invite a friend to play with you!

and

Returns the logical and of the operands.

Syntax: {{and val1 val2 [val3 […]] }}

Example:

YAML Model

motorized: true
aircraft: false
wheels: 2

Template

airliner: {{and motorized aircraft}}
{{#ifb (and motorized (not aircraft) (compare wheels '==' 2))}}
You won a motorcycle!
{{else}}
Sorry, we only offer motorcycles.
{{/ifb}}

Result

airliner: false
You won a motorcycle!

or

Returns the logical or of the operands.

Syntax: {{or val1 val2 [val3 […]] }}

Example:

YAML Model

admin: false
developer: true
accessLevel: 2

Template

committer: {{or admin developer}}
{{#ifb (or admin developer (compare accessLevel '>=' 4))}}
Click here to download the logs.
{{else}}
Sorry, you are not allowed to view the logs.
{{/ifb}}

Result

committer: true
Click here to download the logs.

asJavaId

Converts a value to a valid Java identifier.

Syntax: {{asJavaId value [camelCase=ccBool] [underscore=usBool]}}

You can control the format of the generated Java identifier by specifying the values of the boolean flags camelCase and underscore. The default values are: camelCase = true and underscore = false.

Example:

YAML Model

service: byte-as-an-octet

Template

serviceId: {{asJavaId service}}
package: {{asJavaId service camelCase=false underscore=true}}

Result

serviceId: byteAsAnOctet
package: byte_as_an_octet

asUrlPath

Encodes a string as the path part of a URL.

Syntax: {{asUrlPath value [ascii=aBool]}}

If the ascii flag is true, the string will be encoded so that it only contains characters in the US-ASCII charset. The default value of the ascii flag is false.

Example:

YAML Model

name: Mötley Crüe

Template

Click <a href="http://videos.example.org/{{asUrlPath name}}.mp4">here</a> to download.

Click <a href="http://videos.example.org/{{asUrlPath name ascii=true}}.mp4">here</a> to download.

Result

Click <a href="http://videos.example.org/Mötley%20Crüe.mp4">here</a> to download.

Click <a href="http://videos.example.org/M%C3%B6tley%20Cr%C3%BCe.mp4">here</a> to download.

asUrlQuery

Encodes a string as the query part of a URL.

Syntax: {{asUrlQuery value}}

Example:

YAML Model

url: http://www.example.org/news?id=101

Template

Click <a href="http://translate.example.org?url={{asUrlQuery url}}">here</a> to translate the page.

Result

Click <a href="http://translate.example.org?url=http%3A%2F%2Fwww.example.org%2Fnews%3Fid%3D101">here</a> to translate the page.

javaComment

Inserts the content of a file as a Java comment.

Syntax: {{javaComment 'commentFile'}}

Example:

Template

{{javaComment 'license-header.txt'}}
public class A {}

license-header.txt

This is public-domain software.
Do whatever you want with it.

Result

/*
 * This is public-domain software.
 * Do whatever you want with it.
 */
public class A {}