Handlebars & Helpers

Handlebars

The Novu notification content editor relies on Handlebars.js to establish the logic and control flow of our workflows. For a deeper comprehension of Handlebars.js, you can refer to its documentation.

This resource offers comprehensive insights into the utilization of Handlebars.js in crafting dynamic and adaptable notification content within the Novu platform.

Helper	Description	Example	Output
if	Conditionally renders a block. Falsy values won’t be rendered.	{{#if author}}<h1>{{firstName}} {{lastName}}</h1>{{/if}}	Renders <h1>Yehuda Katz</h1> if author is truthy.
includeZero	includeZero=true treats the conditional as not empty, handling 0 differently.	{{#if 0 includeZero=true}}<h1>Does render</h1>{{/if}}	Renders <h1>Does render</h1> for 0.
Sub-Expressions	Create custom logic helpers and use them in sub-expressions.	{{#if (isdefined value1)}}true{{else}}false{{/if}}	Renders true or false based on custom helper.
unless	Inverse of if helper. Renders a block if the expression is falsy.	{{#unless license}}<h3 class="warning">WARNING</h3>{{/unless}}	Renders warning if license is falsy.
each	Iterate over a list. Use this to reference the iterated element.	{{#each people}}<li>{{this}}</li>{{/each}}	Renders list items.
with	Change context for template parts.	{{#with person}}{{firstname}} {{lastname}}{{/with}}	Renders firstname and lastname from the context.
Nested each	Access iteration variables in nested each blocks.	{{#each array}}{{@index}}: {{this}}{{/each}}	Renders index and item in each iteration.
Nested with	Use with block parameters for clear code.	See above example with nested with and complex template.	Renders nested context values.
	You can use else section to handle empty values.	{{#with city}}...{{else}}No city found{{/with}}	Handles empty context case.

Novu-specific helpers

Handlebar Expression	Description
{{dateFormat date 'EEEE, MMMM Do yyyy'}}	You can format the date using the dateFormat function. Here, date: '2020-01-01' has been formatted into Wednesday, January 1st 2020.
{{lowercase key}}	This helps you use the lowercase handlebar helper function and turns the value of the specified key to its lowercase value. So, for message: 'hEllo WORLD', if we write {{lowercase message}}, we’ll end up with hello world.
{{uppercase key}}	This helps you use the uppercase handlebar helper function and turns the value of the specified key to its uppercase value. So, for message: 'hello woRld', if we write {{uppercase message}}, we’ll end up with HELLO WORLD.
{{titlecase key}}	This helps you use the titlecase handlebar helper function and turns the value of the specified key to its titlecase value. So, for message: 'hEllo wOrLD', if we write {{titlecase message}}, we’ll end up with Hello World.

groupBy

groupBy helper is used to group the items in an array based on a property.

• Template
• Context
• Output

{{#each (groupBy names "name")}}
  <h1>{{key}}<h1>
  {{#each items}}
    <h3>{{age}}</h3>
  {{/each}}
{{/each}}

equals

equals helper allows you to perform comparisons, both for boolean expressions and string comparisons.

• Template
• Context
• Output

<!-- LOGIC -->
{{#equals value1 value2}}
   <!-- Code to execute when value1 is equal to value2 -->
{{else}}
   <!-- Code to execute when value1 is not equal to value2 -->
{{/equals}}


<!-- Example -->
{{#equals 10 1}}
   <h2> 10 is equal to 1 </h2>
{{else}}
   <h1> 10 is not equal to 1 </h1>
{{/equals}}

numberFormat

numberFormat helper is used to format numbers with specified decimal length, thousands separator, and decimal separator.

• Template
• Context
• Output

<div>{{numberFormat number decimalSep="," decimalLength="2" thousandsSep="|"}}</div>
<div>{{numberFormat nonNumber decimalSep="," decimalLength="2" thousandsSep="|"}}</div>

pluralize

The pluralize helper allows you to easily handle pluralization in your templates by providing different forms of a word depending on a variable value.

Basic Usage

In its simplest form, the pluralize helper takes three arguments:

{{pluralize count singular plural}}

• count: The numeric value that determines whether the singular or plural form should be used.
• singular: The singular form of the word.
• plural: The plural form of the word.

Example

{{pluralize dog_count "dog" "dogs"}}

In this example, if dog_count is equal to 1, it will render “1 dog,” and if it’s greater than 1, it will render “dogs.”

Use Cases & Examples

Handling Event Count Display with Excluded Individuals

In some cases, you may want to display the total count of certain events but exclude specific individuals who are already mentioned. For example, when using a phrase like “John and {{step.total_count}} people liked your photo,” you may notice that the count is off by one because “John” is already mentioned.

To account for such scenarios, you can utilize the following approach:

{{#each step.events}}
  {{#if @first}}
    {{this.name}}
  {{else}}
    {{#if @last}}
      and {{@index}}
    {{/if}}
  {{/if}}
{{/each}}
followed you!

In this code, we iterate through the step.events array and conditionally display each name. If it’s the first name in the list, it will be shown without “and.” For subsequent names, we add “and” before the last name. This ensures that the count is not affected by names that are explicitly mentioned in the message.

By using this code, you can achieve a more accurate representation of the event count in your messages, even when some users are individually mentioned in the message text.

Using array length as count

Array length be used as total number of item. For example, if paylod have fruits property of type array then its length can be used as total number of fruits.

• Template
• Payload
• Output

Total number of fruits is {{fruits.length}}.

In a future release, we plan to replace handlebar helpers with an alternative solution. Please note that custom handlebars in the editor itself are not currently supported. If we are missing any handlebar helper that is blocking you to write template for use case, feel free to reach out to us in discord