Handlebars Reference

The Handlebars template engine is used within the tSM Output Management system to render dynamic documents based on JSON input data. This document serves as a complete reference for all custom and built-in Handlebars helpers provided in the system.

How Handlebars Works

Handlebars is a templating engine that allows you to use placeholders in the form of {{property}} to represent data fields. The engine supports the use of helpers—custom functions that provide additional logic and operations within templates.

HTML values need triple braces

Handlebars escapes HTML characters in {{value}}. If your data contain HTML, for example a rich-text field, use triple curly braces: {{{myHtmlData}}}.

Below is a comprehensive list of the helpers available in tSM, including both standard built-in helpers and custom helpers.

Only registered helpers work

If a template calls a helper that is not registered on the server, rendering fails for the whole document instead of leaving the value empty. The Layout Designer then shows an error that names the failing expression, for example {{myHelper value}}, and ends with could not find helper. Verify a helper you have not used before with the live preview or Preview pdf in the Layout Designer.

The Function list of the Handlebars component in the Layout Designer generates these helpers for you, see Handlebars component.

Helper Categories

1. Standard Built-In Helpers

Handlebars provides a set of built-in helpers for basic logic, iteration, and variable management:

• if: Executes a block if the condition is true.

{{#if isAvailable}}
The item is available.
{{else}}
The item is not available.
{{/if}}

The else statement is optional and allows you to define a secondary block for when the condition is false.

• unless: Executes a block if the condition is false.

{{#unless isAvailable}}
The item is not available.
{{/unless}}

This is the inverse of the if helper.

• each: Iterates over a list or array and renders the block for each item.

{{#each items}}
  <li>{{this}}</li>
{{/each}}

In this example, items is an array, and this refers to each item in the array.

• with: Changes the context of the block to the specified value.

{{#with person}}
Name: {{firstName}} {{lastName}}
{{/with}}

The with helper changes the scope to the person object, allowing direct access to its properties.

2. Logical Helpers

• or: Returns true if at least one of the arguments is true.

{{#if (or arg1 arg2)}}
At least one is true.
{{/if}}

• and: Returns true if both arguments are true.

{{#if (and arg1 arg2)}}
Both are true.
{{/if}}

• not: Negates the given boolean argument, returning true if the input is false.

{{#if (not isAvailable)}}
Not available.
{{/if}}

3. Comparison Helpers

• eq: Checks if two values are equal.

{{#if (eq value "expectedValue")}}
Values are equal.
{{/if}}

• ifEquals: Alias for eq that performs the same equality check. Use it as a subexpression, {{#if (ifEquals value 5)}}. As a block, {{#ifEquals value 5}} … {{/ifEquals}} ignores its content and prints only true or false.

• lt: Returns true if the first number is less than the second.

{{#if (lt value 10)}}
Value is less than 10.
{{/if}}

• gt: Returns true if the first number is greater than the second.

{{#if (gt value 10)}}
Value is greater than 10.
{{/if}}

• lte: Returns true if the first number is less than or equal to the second.

• gte: Returns true if the first number is greater than or equal to the second.

• isEmpty: Returns true if the value is empty.

{{#if (isEmpty customer.note)}}
No note.
{{/if}}

4. Variable Management

• setVar: Sets a new variable in the Handlebars context.

{{setVar "myVar" "Hello, World!"}}
{{myVar}}

Output: Hello, World!

5. String Manipulation Helpers

• replace: Replaces a specified substring in a string.

{{replace "Hello, World!" "World" "Handlebars"}}

Output: Hello, Handlebars!

• replaceRegex: Replaces substrings matching a regular expression.

{{replaceRegex "Hello123, World123!" "\d+" ""}}

Output: Hello, World!

• first: Retrieves the first element of a comma-separated list.

{{first "apple,banana,orange"}}

Output: apple

• in: Checks whether a value is one of the items of a list separated by semicolons. The first argument must be a text value. ifIn works the same way.

{{#if (in "apple" "apple;banana;orange")}}
Found the item!
{{/if}}

A comma-separated list such as "apple,banana,orange" does not match.

6. Date and Time Helpers

• formatDate: Formats a date or timestamp to a specified pattern.

{{formatDate "2024-10-04T14:48:00Z" "yyyy-MM-dd"}}

Output: 2024-10-04

• durration: Calculates the duration between two date strings in a specified unit (e.g., YEARS, DAYS, HOURS).

{{durration "2024-10-01T00:00:00Z" "2024-10-04T00:00:00Z" "DAYS"}}

Output: 3

• secondsTime: Converts a time in seconds into hours, minutes and seconds separated by colons, without leading zeros.

{{secondsTime 3661}}

Output: 1:1:1

• parseDate: Parses a date string and extracts a specific unit (e.g., year, month).

{{parseDate "2024-10-04T14:48:00Z" "MONTHS"}}

Output: 10

• calculateDate: Adds or subtracts a time unit from a date.

{{calculateDate "2024-10-04T14:48:00Z" "+" 10 "DAYS" "yyyy-MM-dd"}}

Output: 2024-10-14

7. Math Helpers

• math: Performs basic arithmetic operations (addition, subtraction, multiplication, and division).

{{math 10 "+" 5}}  <!-- Output: 15 -->
{{math 10 "-" 3}}  <!-- Output: 7 -->
{{math 10 "*" 2}}  <!-- Output: 20 -->
{{math 10 "/" 2}}  <!-- Output: 5 -->

8. Output Formatting Helpers

• markdown: Converts Markdown content to HTML. Use it with triple braces, otherwise the generated HTML is escaped and printed as text.

{{{markdown "**Bold text**"}}}

Output: <p><strong>Bold text</strong></p>, rendered as Bold text.

• plaintext: Converts HTML content to plain text.

{{plaintext "<h1>Hello</h1>"}}

Output: Hello

• html: Outputs an HTML value without escaping, like triple braces.

{{html "<b>Important</b>"}}

Output: Important

• htmlToMarkdown: Converts HTML content to Markdown text.

{{htmlToMarkdown "<b>Important</b>"}}

Output: **Important**

• parseNumberFromString: Converts a formatted number string into a numeric value.

{{parseNumberFromString "1 234,56"}}

Output: 1234.56

The input is read in the Czech number format (space as the thousands separator, comma as the decimal separator). An English formatted value such as "1,234.56" is not converted correctly.

9. tSM Helpers

These helpers interact with other modules of the tSM system, providing additional functionality specific to tSM.

• formatMoney: Formats a monetary value. It is the recommended helper for amounts. The default locale is cs-CZ. Supported hash parameters:

  • inputLocale or locale for parsing string input,
  • outputLocale or locale for the result,
  • currency to override the currency,
  • pattern, fractionDigits, minFractionDigits, maxFractionDigits for the number format,
  • nullValue and blankValue for the output of a missing or blank value.

  When a string input cannot be parsed, the original string is returned.

  The examples use amount = 2310.1:

{{formatMoney amount}}

Output: 2 310,1 Kč

{{formatMoney amount fractionDigits=2}}

Output: 2 310,10 Kč

{{formatMoney amount minFractionDigits=0 maxFractionDigits=2}}

Output: 2 310,1 Kč

{{formatMoney amount locale="sk-SK"}}

Output: 2 310,1 €

{{formatMoney amount locale="en-US"}}

Output: $2,310.1

{{formatMoney amount currency="EUR"}}

Output: 2 310,1 €

{{formatMoney amount pattern="#,##0.##" minFractionDigits=3 maxFractionDigits=3}}

Output: 2 310,100

{{formatMoney "2,310.1" inputLocale="en-US" outputLocale="sk-SK"}}

Output: 2 310,1 €

{{formatMoney missingAmount nullValue="-"}}

Output: -

{{formatMoney " " blankValue="n/a"}}

Output: n/a

• formatCurrency: Older currency helper.

Use formatMoney for numbers

formatCurrency does not format plain numbers: {{formatCurrency 2500.5}} renders 0,00 Kč, and a string such as "2500,5" is returned unchanged. Use formatMoney for amounts.

• formatPrice: Parses a price string and formats it with two decimal places, without the currency symbol.

{{formatPrice "2500,5 Kč"}}

Output: 2 500,50

• qrCode: Generates a QR code based on the provided data and optional payment information. A single amount such as {{qrCode 100}} renders nothing, so always check the output with the preview.

• checkBoxText: Renders an empty checkbox followed by the text, as HTML.

{{checkBoxText "Agree to terms?"}}

Output: a checkbox square and the text Agree to terms?

• button: Generates an HTML link styled as a button. Use triple braces, otherwise the link is printed as text.

{{{button "https://example.com" "/action" "Click Me"}}}

Output: <a href='https://example.com/action' target='_blank' class='button'>Click Me</a>

• userById: Retrieves the user name based on a user ID or code.

{{userById "USER123"}}

Output: John Doe. When no user matches, the input is printed unchanged, which also applies to userGroupById.

• userGroupById: Retrieves the name of a user group based on its ID or code.

{{userGroupById "GROUP123"}}

Output: Administrators

• getCiselnikNameByCode: Prints the name of a value of a user register (Configuration → User registers). Pass the register code first and the value code second. When the value is not found, the value code is printed. Registers of other modules, for example ticketing registers, are not looked up.

{{getCiselnikNameByCode "OrderPriority" "HIGH"}}

Output: the name of the HIGH value of the OrderPriority register.

10. Whitespace control

Block helpers such as {{#if}} and {{#each}} leave their line breaks in the output. In text formats such as JSON, XML or plain-text emails this produces empty lines, or a comma that ends up on its own line. A tilde (~) inside the braces removes the whitespace on that side of the tag:

• {{~#if value}} removes whitespace before the tag,
• {{#if value~}} removes whitespace after the tag.

{
  {{#if imsi ~}}
    "imsi": "{{imsi}}"{{#if msisdn}},{{/if}}
  {{/if ~}}
  {{#if msisdn ~}}
    "msisdn": "{{msisdn}}"
  {{/if ~}}
}

Without the tildes, the output contains an empty line between the two properties. With them, the output is compact:

{
  "imsi": "230011234567890",
  "msisdn": "420777123456"
}

The same pattern keeps the comma correct when one of the values is missing.

11. SpEL expressions

The spel helper evaluates a SpEL expression inside a template. It is useful for conditions that are hard to read with nested Handlebars helpers.

{{spel "1 == 1"}}

Output: true

Suppose you want to check whether status is one of several values.

With Handlebars helpers only:

{{#if (or (or (eq status "A") (eq status "B")) (eq status "C"))}}
  "result": "matched"
{{/if}}

With SpEL:

{{#if (spel "status == 'A' or status == 'B' or status == 'C'")}}
  "result": "matched"
{{/if}}

Template data are available in the expression by name, with or without # (status and #status work the same), including nested paths such as order.customer.name. The expression is evaluated on the server during rendering and can use SpEL operators, null safety and string or math functions.

Using Helpers in Output Management

In the context of tSM Output Management, these helpers can be leveraged to build complex document templates, providing dynamic content, logic, and formatting.