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.
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
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
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: & < > " ' ` =
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
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
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
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.
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.
Components Utilizing Handlebars
Below is a list of components that utilize Handlebars. For more details, please refer to the Configuration section of each component.
Component Name | Input Field Name |
---|---|
Box.com | Authentication |
DB Query | Connection Options Query info |
Document Aggregate | Aggregation Pipeline |
Document Count | Query |
Document Delete | Query |
Document Retrieve | Query |
Document Update | Query Update statement |
Generic Resolver | Configuration |
Logger | Message |
Mongo Query | Query |
Template Engine | Input for each Template |