Handlebars

Handlebars is the template engine to generate text output (JSON Objects, XMLs, HTML web pages, e-mails, configuration files, source code, etc.) based on templates and changing data. Templates are written in the Handlebars syntax. Handlebars is used in many components within Xill4.

The section describes the basics of the Handlebars syntax. In addition to the basics, there are a lot of helpers that allow you to do more advanced operations.

note

You can't directly access properties that share a name with one of the helpers. For example, if you have a property named log, you can't access it with {{log}}. You can use {{this.log}} instead.

Basic Usage

Handlebars expressions are some contents enclosed by double curly braces {{}}. In the below template, firstName is a variable that is enclosed by double curly braces, which is said to be an expression.

Template

<p>{{firstName}} {{lastName}}</p>

If the below input object is applied to the template input

{
  "firstName": "Mike",
  "lastName": "Kat"
}

Expressions are compiled to produce the output as follows: output

<p>Mike Kat</p>

HTML-escaping

In Handlebars, the values returned by the {{expression}} are HTML-escaped. Say, if the expression contains &, then the returned HTML-escaped output is generated as &. If you don't want Handlebars to escape a value, use the "triple-stash", {{{.

In the below template, you can learn how to produce the HTML escaped and raw output.

Template

raw:
{{{specialChars}}}
html-escaped:
{{specialChars}}

Pass the special characters to the template

Input

{ "specialChars": "& < > \" ' ` =" }

Expressions enclosed by "triple-stash" {{{ produce the raw output. Otherwise, HTML-escaped output is generated as below. output

raw: & < > " ' ` = html-escaped: &amp; &lt; &gt; &quot; &#x27; &#x60; &#x3D;

note

In the context of Xill4, it is recommended to use the "triple-stash" {{{ to avoid HTML-escaping as in most cases the output is not HTML but JSON.

Path expressions

Handlebars expressions can also be dot-separated paths.

Template

{{person.firstName}} {{person.lastName}}

This expression looks up the person property in the input object and in turn looks up the firstName and lastName property within the person object.

Pass the below input object to the template

Input

{
  "person": {
    "firstName": "Mike",
    "lastName": "Kat"
  }
}

Output will be generated as below

Output

Mike Kat

Changing the context

Some helpers like #with and #each allow you to dive into nested objects. When you include ../ segments in your path, Handlebars will change back into the parent context.

Template

{{#each people}}
    {{../prefix}} {{firstName}}
{{/each}}

Even though the name is printed while in the context of a comment, it can still go back to the main context (the root-object) to retrieve the prefix.

Literal segments

Identifiers may be any unicode character except for the following:

In addition, the words true, false, null and undefined are only allowed in the first part of a path expression.

To reference a property that is not a valid identifier, you can use segment-literal notation, [. You may not include a closing ] in a path-literal, but all other characters are allowed.

JavaScript-style strings, " and ', may also be used instead of [ pairs.

Template

{{!-- wrong: {{array.0.item}} --}}
correct: array.[0].item: {{array.[0].item}}

{{!-- wrong: {{array.[0].item-class}} --}}
correct: array.[0].[item-class]: {{array.[0].[item-class]}}

{{!-- wrong: {{./true}}--}}
correct: ./[true]: {{./[true]}}

includeZero

The includeZero=true option may be set to treat the conditional as not empty. This effectively determines if 0 is handled by the positive or negative path.

{{#if 0 includeZero=true}}
  <h1>Does render</h1>
{{/if}}

Template comments

The comments will not be in the resulting output. If you'd like the comments to show up. Just use HTML comments, and they will be output.

{{! This is a comment }}