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

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.

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

You can 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

Helpers can be nested:

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

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

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

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

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

Overview

Data Quality & Observability

Handlebars Templating Guide

Handlebars Templating Guide

Understanding Handlebars

Basic Syntax

Variable Interpolation

Conditional Logic

Else Blocks

Looping Through Lists

Nested Logic

Using Helpers

Basic Helper Syntax

Helpers with Parameters

Nesting Helpers

Context Objects

Common Patterns

Accessing Nested Properties

Default Values with If

Formatting Output

Building Links

Important Notes

Property Access

Empty String Rendering

HTML Escaping

Spaces in Output

Next Steps

​Handlebars Templating Guide

​Understanding Handlebars

​Basic Syntax

​Variable Interpolation

​Conditional Logic

​Else Blocks

​Looping Through Lists

​Nested Logic

​Using Helpers

​Basic Helper Syntax

​Helpers with Parameters

​Nesting Helpers

​Context Objects

​Common Patterns

​Accessing Nested Properties

​Default Values with If

​Formatting Output

​Building Links

​Important Notes

​Property Access

​Empty String Rendering

​HTML Escaping

​Spaces in Output

​Next Steps

Handlebars Templating Guide

Understanding Handlebars

Basic Syntax

Variable Interpolation

Conditional Logic

Else Blocks

Looping Through Lists

Nested Logic

Using Helpers

Basic Helper Syntax

Helpers with Parameters

Nesting Helpers

Context Objects

Common Patterns

Accessing Nested Properties

Default Values with If

Formatting Output

Building Links

Important Notes

Property Access

Empty String Rendering

HTML Escaping

Spaces in Output

Next Steps