Skip to main content
Version: Next

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

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.