Advanced templating (Handlebars)
Using the Handlebar templating engine to create advanced templates
Last updated
Was this helpful?
Using the Handlebar templating engine to create advanced templates
Last updated
Was this helpful?
By default, Lob uses a based on Mustache. If you would like to render complex personalizations, use the alternate Handlebars templating engine route through Lob API. allows you to populate, evaluate, and iterate using templates and API requests. The biggest advantage of this approach is quickly creating dynamic personalization without making any changes to your codebase. We can use advanced templating to make dynamic tables.
Start with any Handlebars-friendly template. Dynamic variables should be wrapped in double curly braces {{like_this}}
. To the right is an example of a simple handlebars
template.
To push your template to a Lob environment, use the API. Creating Handlebars templates via the Dashboard UI is not supported at this time. To specify that our service should use the Handlebars templating engine, you will need pass handlebars
in the template request engine
field as shown on the right.
You can use this newly created endpoint to test that your Handlebars template compiles as expected. To do that, use the /v1/templates/
endpoint and add your merge variable(s) as a dynamic URL query parameter. You can use this to inspect how your template will display with the merge variables passed in. The response is the same format that Lob will use to render your mailpiece.
Now that your template has been created in a Lob environment, the templating engine
has been set to handlebars
, and you've tested out your template using the Template Compilation API, you can send a mailpiece request to the /v1/checks/
, /v1/postcards/
, /v1/letters/
or /v1/self_mailers/
endpoint as you normally would. In the request message body, use the merge_variables
field to pass in dynamic values.
The below helpers can be used for many dynamic use cases. Helpers like if
blocks can include nested built-in and customer helper conditionals (like if
, and
, or
, eq
, etc).
You can use the if
helper to conditionally render a block. If its argument returns false
, undefined
, null
, ""
, 0
, or []
, Handlebars will not render the block.
When you pass the following input to the above template:
This will produce the result as below:
If the input is an empty JSONObject {}
, then author
will become undefined
and if
condition fails, resulting in the output as follow:
When using a block expression, you can specify a template section to run if the expression returns a falsey value. The section, marked by else
is called an "else section".
Custom helpers are additional functions that can assist in the formatting of your document. The documentation here is directly pulled from the associated third-party . The helpers below are supported.
Returns all of the items in an array after the specified index. Opposite of .
Return all of the items in the collection before the specified count. Opposite of .
Returns the last item, or last n
items of an array or string. Opposite of .
Use the items in the array after the specified index as context inside a block. Opposite of .
Use the items in the array before the specified index as context inside a block. Opposite of .
Use the first item in a collection inside a handlebars block expression. Opposite of .
Use the last item or n
items in an array as context inside a block. Opposite of .
Block helper that return an array with all duplicate values removed. Best used along with a helper.
Render a block when a comparison of the first and third arguments returns true. The second argument is the to use. You may also optionally specify an inverse block to render when falsey.
Returns true if the given value
is falsey. Uses the library for comparisons. Please see that library for more information or to report bugs with this helper.
Returns true if the given value
is truthy. Uses the library for comparisons. Please see that library for more information or to report bugs with this helper.
Block helper that renders a block if a
is equal to b
. If an inverse block is specified it will be rendered when falsey. Similar to but does not do strict equality.
Block helper that renders a block if a
is not equal to b
. If an inverse block is specified it will be rendered when falsey. Similar to but does not use strict equality for comparisons.
Lowercase all of the characters in the given string. Alias for .
Truncate a string to the specified length
. Also see .
Truncate a string to have the specified number of words. Also see .
Uppercase all of the characters in the given string. Alias for .