Skip to main content

​
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

SyntaxPurposeExample
{{variableName}}Insert a value{{entity.name}}
{{#if condition}}...{{/if}}Conditional display{{#if entity.owner}}Owner: {{entity.owner}}{{/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.owner}}
  <p>Owner: {{entity.owner}}</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.owner}}
  <p>Owner: <strong>{{entity.owner}}</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.
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.owner}}
  {{#if entity.tags}}
    <p>{{entity.owner}} manages this entity with {{length entity.tags}} tags</p>
  {{/if}}
{{/if}}

​
Using Helpers

Helpers are functions that perform operations on your data. Collate provides 22 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.owner.displayName}}
{{event.changeDescription.updates}}

​
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}}
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.owner.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>Owner: {{entity.owner}}</p>
If entity.owner is missing, renders as: 
<p>Owner: </p>
Use conditionals to prevent this: 
{{#if entity.owner}}
  <p>Owner: {{entity.owner}}</p>
{{/if}}

​
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