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.

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

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.

• 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.

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 if a substring is present in a given string.

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

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 HH:mm:ss format.

{{secondsTime 3661}}

Output: 01:01:01

• 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.

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

Output: <strong>Bold text</strong>

• plaintext: Converts HTML content to plain text.

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

Output: Hello

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

{{parseNumberFromString "1,234.56"}}

Output: 1234.56

9. tSM Helpers

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

• formatCurrency: Formats a numeric value into a currency string according to locale settings.

{{formatCurrency 2500.5}}

Output: 2,500.50 Kč

• formatPrice: Formats a number to two decimal places and removes currency symbols.

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

Output: 2500.50

• qrCode: Generates a QR code based on the provided data and optional payment information.

{{qrCode 100}}

• checkBoxText: Renders a formatted HTML checkbox text.

{{checkBoxText "Agree to terms?"}}

Output: <div class="fake-checkbox"></div> Agree to terms?

• button: Generates an HTML button with a specified link and label.

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

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

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

{{userById "USER123"}}

Output: John Doe

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

{{userGroupById "GROUP123"}}

Output: Administrators

10. Removing newline

When generating conditional output using Handlebars ({{#if}} blocks), it's common to encounter unwanted formatting issues such as:

• Empty lines in the output (especially when values are missing),
• Commas ending up on a separate line from the value.

To avoid this, use whitespace control (~) combined with inline conditional logic to produce compact and valid output.

Recommended pattern:

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

Output Example:

//Unoptimized example:
{
  "myVar":"My line 1",
  
  "myVar2":"My line 2"
}

// Optimized version using ~:
{
  "myVar":"My line 1",
  "myVar2":"My line 2"
}

11. Using SpEL for complex expressions

tSM Output Management supports SpEL (Spring Expression Language) to evaluate more complex conditions and expressions in templates.

SpEL can be used inside Handlebars templates using the spel helper function. This gives you more expressive power compared to standard Handlebars logic.

Handlebars vs. SpEL: Comparison example

Suppose you want to check if a variable (myVar1) matches one of several specific values (e.g. "A", "B", "C").

1. Handlebars only version:

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

This works, but gets hard to read as conditions grow.

2. Using spel expression:

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

Where you can use spel

Inside {{#if (spel "...")}} conditions Inside {{#unless}}, {{#each}}, or custom helpers (if supported)

Tip: SpEL is evaluated at runtime inside the tSM rendering engine. It gives you access to full logical operations, null safety, type casting, math, string functions, etc.

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.