The Handlebars implementation in OL Connect offers a straightforward way to incorporate dynamic content into your templates. In this post, we’ll dive into various methods for dynamically reading snippets in an OL Connect template using Handlebars, highlighting the benefits and considerations of each approach.

Introduced in OL Connect 2023.2, Partial helpers let you import Handlebars snippet contents using an expression. The Partial helper syntax involves using the plus sign followed by the name of the snippet. The following loads the content of the snipped called ‘helloworld.hbs’ and places the content at that location.

{{+ helloworld.hbs}} or simply {{+ helloworld}}

Let’s delve into techniques to dynamically load a snippet based on a data value.

Using If-Statements with Partial helpers

An obvious approach to dynamically include snippets is combining if-statements with Partial helpers. This approach is intuitive and aligns well with Handlebars’ logic-based syntax. However, it’s not without drawbacks when combined with one or more conditional statement in the main editor.

One notable side effect is the potential addition of unwanted white space before the content, which can affect the layout of your document. Checking against multiple values can quickly take up considerable space and displace other content even more as shown in the image below.

The sample uses two if statements and the Partial helper to load a snippet based on a condition. It loads the partial by comparing the value stored in the ‘product’ data field. The extra white space stems mainly from the added indentation to improve the readability of the if statements, which the internal layout engine tries to maintain.

Note! In OL Connect 2024.1 you’ll be able to use ‘else if’ construction instead of using nested ‘if’ statements.
Note! Loading Partials is not limited to just snippets located in the template. They can also be utilized to load snippets from a disk or from an endpoint (which could facilitate a search in a database or CMS). For instance, you can load a partial from a URL like this: {{+ http://localhost:1880/policies?p=travel}}

Move the If-Statements to a Partial

A notable Handlebars feature is the ability for snippets to reference or load other snippets. By transferring the logic to a snippet, it enables the snippet to load the required snippets, which reduces clutter in the main editor and resolves the whitespace issue.

In this scenario the logic was moved to the product.hbs, which is added using a Partial helper to the main editor. The following image shows the snippets folder with the ‘root’ snippet called product and the two snippets holding product data (adapters and fittings).

This way, you can adapt the content in the document based on varying conditions without compromising on readability.

Dynamic Partials using a Sub Expression

Another useful trick in Handlebars is the use of sub expression syntax. This comes in handy when the name of your snippet is saved in a data field. With the sub expression syntax, which involves placing the data field name within parentheses, you can dynamically reference these snippets. For instance, if the snippet’s name is held in a data field called ‘productName’, you would use:

{{+ (productName)}}

In our example, if the ‘productName’ field’s value is ‘adapters’, then the ‘adapters.hbs’ snippet will be automatically loaded.

Note! In OL Connect 2024.1 you will be able to use the Concat helper to combine the value of multiple data fields and static text. For example {{+ (concat productName "_" lang)}}, which may result in ‘adapters_EN’.

Dynamic Partials using a Text Helper

This method allows you to concatenate data and static values in an even cleaner way, resulting in a shorter expression which enhances the readability of your template.

Crafting a Custom Helper

For those seeking the utmost flexibility, crafting a custom helper is the way to go. This approach allows you to encapsulate complex logic and generate dynamic content based on your specific requirements. This is done in a Control Script.

Example of a simple custom helper (no specific logic was added):

Handlebars.registerHelper("productHelper", function(){
	let snippetPath = `snippets/${record.fields.productName}.hbs`
	let result = Handlebars.render(snippetPath); 
	return new Handlebars.SafeString( result );
})

Or

Handlebars.registerHelper("productHelper", function(){
	let result = Handlebars.render("{{+(productName)}}"); 
	return new Handlebars.SafeString( result );
})

Include this helper in your template just like any standard Handlebars expression: {{productHelper}}. While this allows you to leverage the power of the Handlebars API with JavaScript, it also means you need to know JavaScript to make it work.

Conclusion

By implementing one of these methods, you can tailor your OL Connect templates to handle Handlebars snippets dynamically. Whether you opt for the simplicity of partials, the flexibility of dynamic partial names, the cleanliness of dynamic partials using a Text helper, or the power of a custom helper, each approach offers a unique solution to suit your template customization needs. Choose the method that aligns with your project’s requirements.

Leave a Reply