Handlebars Templating Guide

Handlebars is a templating language that lets you insert dynamic data and add logic to your templates. This guide covers the basics you need to write notification templates.

Understanding Handlebars

Handlebars uses double curly braces {{ and }} to mark placeholders where dynamic content will be inserted. For complete Handlebars documentation, see Handlebars Official Guide.

Basic Syntax

The table below summarises the core Handlebars constructs used in notification templates.

Syntax	Purpose	Example
`{{variableName}}`	Insert a value	`{{entity.name}}`
`{{#if condition}}...{{/if}}`	Conditional display	`{{#if entity.owners}}Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}{{/if}}`
`{{#each array}}...{{/each}}`	Loop through lists	`{{#each entity.tags}}{{this}}{{/each}}`
`{{helper arg1 arg2}}`	Call a helper function	`{{formatDate entity.updatedAt}}`

Variable Interpolation

Insert dynamic values into your templates using {{variableName}} syntax:

Entity: {{entity.name}}
Updated by: {{event.userName}}
Type: {{event.entityType}}

When this template renders, the placeholders are replaced with actual values from the event:

Entity: customer_data
Updated by: john.doe
Type: table

Conditional Logic

Use {{#if}} blocks to show content only when a condition is true:

{{#if entity.owners}}
  <p>Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}</p>
{{/if}}

This section only appears if the entity has an owner. If the field is empty, the entire block is hidden.

Else Blocks

Add {{else}} to provide alternative content:

{{#if entity.owners}}
  <p>Owner: <strong>{{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}</strong></p>
{{else}}
  <p>This entity has no owner assigned.</p>
{{/if}}

Looping Through Lists

Use {{#each}} to iterate through arrays:

<h3>Tags:</h3>
<ul>
  {{#each entity.tags}}
    <li>{{this}}</li>
  {{/each}}
</ul>

For each item in the tags array, this creates a list item. Use {{this}} to refer to the current item. With Object Properties:

{{#each entity.tags}}
  <li>{{tagFQN}}: {{source}}</li>
{{/each}}

Access properties of objects in the array. Looping Through Owners: An entity can have more than one owner, so entity.owners is a list. Each item has id, name, displayName, and type. Use the lowercase name entity.owners. Handlebars is case-sensitive, so entity.Owners renders nothing.

{{#if entity.owners}}
  <p>Owners:
  {{#each entity.owners}}
    {{displayName}} ({{name}}){{#unless @last}}, {{/unless}}
  {{/each}}
  </p>
{{/if}}

displayName can be empty for some owners. Use {{name}} if you need a value that is always set.

Tip: Combine conditional logic with loops to show content only when list items exist:

{{#if (gt (length entity.tags) 0)}}
  <h3>Tags ({{length entity.tags}}):</h3>
  <ul>
    {{#each entity.tags}}
      <li>{{tagFQN}}</li>
    {{/each}}
  </ul>
{{/if}}

Nested Logic

Nest conditions and loops:

{{#if entity.owners}}
  {{#if entity.tags}}
    <p>{{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}} manages this entity with {{length entity.tags}} tags</p>
  {{/if}}
{{/if}}

Using Helpers

Helpers are functions that perform operations on your data. Collate provides 24 custom helpers beyond standard Handlebars features.

Basic Helper Syntax

Call helpers by name with arguments in parentheses:

{{formatDate entity.updatedAt}}
{{camelCaseToTitle event.entityType}}
{{math (length failedTests) '+' 5}}

Helpers with Parameters

Some helpers take parameters:

{{split entity.fullyQualifiedName '.'}}
{{limit failedTests 5}}
{{filter testResults status="Failed"}}

Nesting Helpers

Nest helpers for more complex logic:

{{limit (filter testResults status="Failed") 5}}

This filters tests to show only failed ones, then limits the display to 5 items.

Tip: Use with to assign helper results to a variable for cleaner code:

{{#with (filter testResults status="Failed") as |failedTests|}}
  Failed test count: {{length failedTests}}
{{/with}}

Context Objects

Templates have access to special objects containing event and entity data:

event - The change event that triggered the notification.
entity - The entity being notified about.
subscription - Information about the event subscription.
baseUrl - Base URL of your Collate instance.

For detailed information about available properties, see Template Context Reference.

Common Patterns

The following patterns cover the most frequent template-writing scenarios.

Accessing Nested Properties

Use dot notation to access nested object properties:

{{entity.owners.0.displayName}}
{{event.changeDescription.fieldsUpdated.0.name}}

Default Values with If

Show a default message when data is missing:

{{#if entity.description}}
  <p>{{entity.description}}</p>
{{else}}
  <p>No description available</p>
{{/if}}

Formatting Output

Use helpers to format data:

Updated: {{formatDate entity.updatedAt}}
Type: {{camelCaseToTitle event.entityType}}

Building Links

Use the buildEntityUrl helper to create clickable links to entities:

<a href="{{buildEntityUrl event.entityType entity}}">
  {{entity.fullyQualifiedName}}
</a>

This creates a link that opens the entity in Collate UI.

Important Notes

Keep these behaviours in mind when writing templates to avoid rendering issues.

Property Access

Handlebars uses dot notation (.) to access properties:

entity.name - Access the name property.
entity.owners.0.id - Access nested properties.
entity.tags.0.name - Access array items by index.

Empty String Rendering

If a property doesn’t exist or is empty, Handlebars renders an empty string:

<p>Description: {{entity.description}}</p>

If entity.description is missing, renders as:

<p>Description: </p>

Use conditionals to prevent this:

{{#if entity.description}}
  <p>Description: {{entity.description}}</p>
{{/if}}

HTML Escaping

Double braces {{ }} escape HTML characters in the value. For example, < becomes < and & becomes &. Use them in the template body for plain-text values such as names. Triple braces {{{ }}} output the value with no escaping. Use them for content that is already HTML, such as the table from renderTableSample and rich-text descriptions:

{{{renderTableSample entity.failedRowsSample}}}
{{{processMentions entity.description}}}

A description saved in the Collate UI contains HTML tags, so with double braces the notification shows those tags as text. Email notifications remove unsafe tags such as <script>. The email subject is plain text, so escaped characters appear literally. For example, {{entity.name}} shows Sales & Marketing for an entity named Sales & Marketing. Use triple braces for names in the subject:

[{{event.eventType}}] {{{entity.name}}}

Spaces in Output

Handlebars preserves whitespace and line breaks. Be careful with formatting:

{{entity.name}}

Renders on its own line. To control spacing, use:

Name: {{entity.name}},
Type: {{event.entityType}}

Next Steps

Explore Collate’s helpers → Custom Helpers Reference
Learn available data → Template Context Reference