Skip to Content
Template Helpers

Template Helpers

oJo templates use Handlebars  syntax, not Liquid: {{name}}, {{#if paid}}…{{/if}} and {{#each items}}…{{/each}}, and helpers take their arguments after the name, as in {{uppercase name}} rather than {{ name | upcase }}. The helpers below are built in.

The formatting and text helpers (formatCurrency, formatNumber, formatDate, uppercase, lowercase, capitalize, substring) print nothing for a value the request did not send. math, round, inc and dec print NaN.

Data Manipulation

JSON Conversion

  • json: Writes a value as JSON. The output is safe inside a <script> block: <, > and & are escaped, so a value containing </script> cannot end the script.
<script>
  const chart = {{json chart}};
</script>
  • array: Same as json, for an array value
const labels = {{array labels}}; <!-- labels: ["Q1", "Q2"] → ["Q1","Q2"] -->

String Operations

  • concat: Concatenates multiple strings
{{concat 'Hello' ' ' 'World'}} <!-- Output: Hello World -->
  • lowercase: Converts string to lowercase
{{lowercase 'HELLO'}} <!-- Output: hello -->
  • uppercase: Converts string to uppercase
{{uppercase 'hello'}} <!-- Output: HELLO -->
  • capitalize: Capitalizes first letter of string
{{capitalize 'hello'}} <!-- Output: Hello -->
  • substring: Extracts part of a string
{{substring 'Hello World' 0 5}} <!-- Output: Hello -->

Numeric Operations

Math Operations

  • math: Performs basic mathematical operations
{{math value1 '+' value2}}
<!-- Addition -->
{{math value1 '-' value2}}
<!-- Subtraction -->
{{math value1 '*' value2}}
<!-- Multiplication -->
{{math value1 '/' value2}}
<!-- Division -->
{{math value1 '%' value2}}
<!-- Modulo -->

Number Manipulation

  • round: Rounds a number to specified decimals
{{round 3.14159 2}} <!-- Output: 3.14 -->
  • inc: Increments a number by 1
{{inc 5}} <!-- Output: 6 -->
  • dec: Decrements a number by 1
{{dec 5}} <!-- Output: 4 -->

Number Formatting

Number and currency formats use US English separators (1,234.50).

  • formatNumber: Formats a number with commas. Options of Intl.NumberFormat go after it as name=value.
{{formatNumber 1000}} <!-- Output: 1,000 -->
{{formatNumber 1234.5 minimumFractionDigits=2}} <!-- Output: 1,234.50 -->
{{formatNumber 0.92 style='percent'}} <!-- Output: 92% -->
  • formatCurrency: Formats a number as currency, with the currency’s usual decimals
{{formatCurrency 1000 'USD'}} <!-- Output: $1,000.00 -->
{{formatCurrency 1000 'JPY'}} <!-- Output: ¥1,000 -->
  • formatCurrency: Optional minimum and maximum decimals
{{formatCurrency 1000 'EUR' 0}} <!-- Output: €1,000 -->
{{formatCurrency 1000 'USD' 0 1}} <!-- Output: $1,000 -->

Comparison Helpers

Basic Comparisons

  • eq: Equality comparison
{{#if (eq value1 value2)}}
  Values are equal
{{/if}}
  • gt: Greater than comparison
{{#if (gt value1 value2)}}
  Value1 is greater than Value2
{{/if}}
  • lt: Less than comparison
{{#if (lt value1 value2)}}
  Value1 is less than Value2
{{/if}}
  • gte, lte: Greater than or equal, less than or equal
{{#if (gte score 90)}}
  With distinction
{{/if}}

eq does not convert text to numbers: (eq "90" 90) is false. Two text values compare as text: (gt "100" "90") is false. Send numbers as JSON numbers.

Logic

  • and, or: True when all, or any, of two or more values are truthy
  • not: Negates a value
{{#if (and paid (not refunded))}}
  Paid
{{/if}}

Conditional Operations

  • ternary: Conditional (ternary) operator
{{ternary condition 'Yes' 'No'}}

Date and Time

Date Formatting

  • formatDate: Formats a date using dayjs format tokens . Send dates as ISO 8601 (2024-11-06): a date like 07/10/2026 is read month first, as July 10. A date with a time and offset is shown in UTC.
{{formatDate date 'YYYY-MM-DD'}}
<!-- Output: 2024-11-06 -->
{{formatDate date 'MMM DD, YYYY'}}
<!-- Output: Nov 06, 2024 -->

Date Comparisons

  • isBefore: Checks if one date is before another
{{#if (isBefore date1 date2)}}
  Date1 is before Date2
{{/if}}
  • isAfter: Checks if one date is after another
{{#if (isAfter date1 date2)}}
  Date1 is after Date2
{{/if}}

Array Operations

  • len: Gets array length
{{len array}} <!-- Output: number of items in array -->

Loop Operations

  • times: Repeats a block n times. @index counts from 0.
{{#times 3}}
  Iteration {{inc @index}}
{{/times}}
<!-- Output: Iteration 1 Iteration 2 Iteration 3 -->

Best Practices

  1. Always validate input data before using helpers that perform calculations
  2. Use date formatting helpers with valid date strings
  3. Handle potential undefined values when using array operations
  4. Consider performance impact when using complex helpers in loops
  5. Test helper output with various input types to ensure proper handling
MCP ServerSafe Retries