Using logic in a Handlebars template: helpers

Block helpers

Functions that can be called from a Handlebars expression are called helpers. Handlebars offers a number of built-in block helpers that let you use logic in templates. Block helpers look like this: {{#helperName arguments}}...{{/helperName}}.

They are documented on Handlebars' website: https://handlebarsjs.com/guide/builtin-helpers.html.

Of those helpers, the following are supported in OL Connect:

• #if: Conditionally renders a block. An optional {{else}} section inside the block will display when the condition is not true.

• #unless: Renders a block if the expression returns a falsy value (i.e. a value that is considered false when encountered in a Boolean context). An optional {{else}} section inside the block will display when the condition is true.

• #each: Allows to iterate over a list. An optional {{else}} section inside the block will display when the list is empty.

• #with: Can be used to work directly with the passed object or object property. An optional {{else}} section will display only when the passed value is empty.

In block helpers, the data variables @first, @last, @index can be used; see https://handlebarsjs.com/api-reference/data-variables.html.

Unlike in the original Handlebars library, content provided by a block helper is not automatically HTML-escaped in OL Connect. Blocks are typically used to generate HTML, so it is assumed that the result consists of well-formed HTML.

Examples of block helpers

#if

The following #if block will output a table row with two cells if the data field named O_L10095 is not false, undefined, null, 0, an empty string, or an empty array.

{{#if O_L10095}}
<tr>
	<td>Collective insurance</td>
	<td>{{O_L10095}}</td>
</tr>
{{/if}}

#unless and #each

The following Handlebars template outputs a row with a header and a variable number of clause descriptions, based on a detail table called 'Clause', unless there are no clauses, in which case the row gets a header and one cell that displays the text 'None'.

<table class="policy-table">
<tbody>
{{#unless Clause}}
<tr>
	<th class="h3">Clause(s)</th> 
	<td>None</td>
</tr>
{{else}}
	{{#each Clause}}
	<tr>
		<th class="h3">{{#if @first}}Clause(s){{/if}}</th>
		<td>{{Descr}}</td>
	</tr>
	{{/each}}
{{/unless}} 
</tbody>
</table>

#with and #each

This #with block calls a custom helper (see Adding custom helpers) that returns an object with the properties: object, amount, coverage and premium. The object's properties are accessed directly inside the block. The #with block is executed for each of the records in a detail table called 'insurance_coverage'.

{{#each insurance_coverage}} 
	{{#with (getObjectAndCoverage)}} 
	<tr> 
		<td>{{object}}</td>
		<td class="curr">€</td>	
		<td>{{amount}}</td> 
		<td>{{coverage}}</td> 
		<td class="curr">€</td> 
		<td>{{premium}}</td>
	</tr>
	{{/with}} 
{{/each}}

Additional helpers in OL Connect

OL Connect provides the following additional helpers.

• eq, neq (equal, not equal) - tests two values for equality

• gt (greater than), gte (greater than or equal), lt (lower than), lte (lower than or equal) - compares two numbers

• not, or, and - logical operators

• add - adds two numbers

• sub - subtracts two numbers

• startsWith - tests if a string starts with a certain prefix

• endsWith - tests if a string ends with a certain suffix

• matches - tests if a string matches a regular expression

These can be used as expression (returns the result). For example:
<p>Recurs every month: {{eq 'Monthly' recurrence}}</p>

They can also be used in sub expressions, for example of a block helper:
<p> {{#if (eq 'Monthly' recurrence)}} Recurs every month {{/if}} </p>

Adding custom helpers

In both Handlebars and OL Connect, a number of helpers are predefined, but you can also create your own helpers using Handlebars.registerHelper(). See the Handlebars guide: https://handlebarsjs.com/guide/#custom-helpers.

Examples of custom helpers

Date

The following code registers a function that returns the current date.

Handlebars.registerHelper('now', function() { return new Date(); 
});

After the helper is registered, the expression {{dateLong now}} in a Handlebars template will return the current date, formatted as a long date, e.g. February 23, 2022.

Get coverage

This helper returns an object whose properties are filled with values based on data fields in the current context (this). For example, when called within an #each block that is executed with the records of a detail table, this refers to the current detail table record. (See also: #with and #each.)

Handlebars.registerHelper('getObjectAndCoverage', function () { 
	let coverage = this.O_L99042; 
	let category = this.C_L99042 
	if( category === 'extra' ) {
			coverage = 'Extra + glass';	
	} 
	return { 
		"object": "Residential building", 
		"amount": this.L10039D, 
		"coverage": coverage, 
		"premium" : this.L10145 
	} 
})

HTML-escaping in a helper

If a helper needs to HTML-escape a string you can call Handlebars.escapeHTML() in that function.
For example, if you would want to HTML-escape the value of this.field, but not "<p>" or "</p>", you could write:
function() { return "<p>" + Handlebars.escapeHTML(this.field) + "</p>"; }
In the original Handlebars library this function is called Handlebars.escapeExpression().