Strings

abbreviate

Truncates text with an ellipsis when it exceeds the width.

{{abbreviate title 13}}

Data:

{
  "title": "Handlebars rocks"
}

Output:

Handlebars...

capitalize

Capitalizes every whitespace-separated word.

{{capitalize title}}

Data:

{
  "title": "my first post"
}

Output:

My First Post

Fully normalize capitalization:

{{capitalize title fully=true}}

Data:

{
  "title": "mY FIRST pOSt"
}

Output:

My First Post

capitalizeFirst

Capitalizes the first character.

{{capitalizeFirst title}}

Data:

{
  "title": "handlebars.java"
}

Output:

Handlebars.java

center

Centers text in a field of a given width.

'{{center name size=10}}'

Data:

{
  "name": "Bob"
}

Output conceptually:

'   Bob    '

Use custom padding:

{{center name size=9 pad="-"}}

concat

Returns the concatenation of the arguments.

Usage:

 {{concat 123 ':' 45 }} → 123:45

Null values will be cast to empty strings. See the similar XPath 1.0 function.

cut

Removes all occurrences of a substring. The default substring is a space.

{{cut text}}

Data:

{
  "text": "String with spaces"
}

Output:

Stringwithspaces

Custom cut string:

{{cut sku "-"}}

defaultIfEmpty

Returns a default value when the input is empty.

{{defaultIfEmpty nickname "Anonymous"}}

Data:

{
  "nickname": ""
}

Output:

Anonymous

join

Joins iterable, iterator, array, or multiple values.

{{join tags ", "}}

Data:

{
  "tags": [
    "java",
    "handlebars",
    "template"
  ]
}

Output:

java, handlebars, template

With prefix/suffix:

{{join tags ", " prefix="[" suffix="]"}}

Output:

[java, handlebars, template]

Join positional values:

{{join "a" "b" "c" " / "}}

Output:

a / b / c

ljust

Left-aligns text by padding on the right.

'{{ljust name size=10}}'

Data:

{
  "name": "Bob"
}

Output conceptually:

'Bob       '

lower

Converts text to lowercase.

{{lower title}}

Data:

{
  "title": "Still MAD At Yoko"
}

Output:

still mad at yoko

normalizeSpace

Returns the argument string with the leading, trailing, and repeating white spaces stripped.

{{normalizeSpace 'a b   c  ' }} → "a b c"
{{normalizeSpace true }} → "true"

See the similar XPath 1.0 function.

numberFormat

Formats Java Number values.

{{numberFormat price "#,###.00"}}

Data:

{
  "price": 1234.5
}

Output:

1,234.50

Predefined styles:

{{numberFormat price "integer"}}
{{numberFormat ratio "percent"}}
{{numberFormat price "currency" locale="en_US"}}

Fraction options:

{{numberFormat
        price
        maximumFractionDigits=2
        minimumFractionDigits=2
        roundingMode="HALF_UP"
}}

Disable grouping:

{{numberFormat price groupingUsed=false}}

rjust

Right-aligns text by padding on the left.

'{{rjust name size=10}}'

Data:

{
  "name": "Bob"
}

Output conceptually:

'       Bob'

replace

Replaces all literal occurrences of a target substring.

{{replace text "..." "rocks"}}

Data:

{
  "text": "Handlebars ..."
}

Output:

Handlebars rocks

replaceAll

Replaces each substring of the input string applying the regular expression in the first parameter and using th second parameter as the replacement pattern.

Usage:

{{replaceAll value '^(.+)/(\w+)$' "$1 (ext=$2)" }}
{{replaceAll value '(?im)^(.+)/(\w+)$' "$1 (ext=$2)" }}

If the value is Handlebars/png, the output will be Handlebars (ext=png).

To set global flags, you can prefix the expression with (?i) or (?m), (?im). The evaluation is always global. This uses the Java semantics for regex.

slugify

Converts text to a simple lowercase slug. This implementation keeps letters and converts whitespace to hyphens.

{{slugify title}}

Data:

{
  "title": "Joel is a slug"
}

Output:

joel-is-a-slug

string

Converts an object to a string.

 {{string true }} → "true"
{{string 123 }} → "123"

See the similar XPath 1.0 function.

Note: Different from XPath the string representation of an array or of an object is not the concatenation of all plain text values. Instead, it produces a string representation of the complete object tree as defined in the Java programming language.

stringFormat

Uses Java String.format.

{{stringFormat "Hello %s" name}}

Data:

{
  "name": "Handlebars.java"
}

Output:

Hello Handlebars.java

Number formatting example:

{{stringFormat "%.2f" price}}

Data:

{
  "price": 123.4567
}

Output:

123.46

stringLength

Returns the number of characters in the string.

{{stringLength 'abcd' }} → 4
{{stringLength 'ab cd' }} → 5

If an argument is not of type string, it is first converted to a string and then evaluated.

See the similar XPath 1.0 function.

stripTags

Removes HTML/XML tags.

{{stripTags html}}

Data:

{
  "html": "<p>Hello <strong>world</strong></p>"
}

Output:

Hello world

substring

Returns a substring by start and optional end index.

{{substring value 11}}

Data:

{
  "value": "Handlebars.java"
}

Output:

java

With end index:

{{substring value 0 10}}

Output:

Handlebars

substringAfter

Returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string. See the similar XPath 1.0 function.

substringBefore

Returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string. See the similar XPath 1.0 function.

translate

Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string.

This function provides a mapping of characters on the first argument. The second and third arguments describe the scheme of the mapping.

If there is a character in the second argument string with no character at a corresponding position in the third argument string (because the second argument string is longer than the third argument string), occurrences of that character in the first argument string are removed. If a character occurs more than once in the second argument string, the first occurrence determines the replacement character. If the third argument string is longer than the second argument string, excess characters are ignored.

{{translate 'bar' 'abc' 'ABC' }} → BAr
{{translate '--aaa--' 'abc-' 'ABC' }} → AAA

If an argument is not of type string, it is first converted to a string and then evaluated.

See the similar XPath 1.0 function.

unescapeHtml

Returns a string with all HTML escaped characters in raw form.

{{{unescapeHtml title }}}

Data:

{
  "title": "<Français>"
}

Output:

<Français>

upper

Converts text to uppercase.

{{upper title}}

Data:

{
  "title": "Hello"
}

Output:

HELLO

wordWrap

Wraps text at the requested width.

{{wordWrap text 5}}

Data:

{
  "text": "Joel is a slug"
}

Output conceptually:

Joel
is a
slug

yesno

Maps boolean/null values to strings.

{{yesno published}}

Data:

{
  "published": true
}

Output:

yes

Custom labels:

{{yesno published yes="published" no="draft" maybe="unknown"}}

For null, the helper returns the maybe value.