Advanced string templates in Mendix with {{ Handlebars.java }}
When working with Mendix, there are a number of scenarios where a dynamic string template is required. A common use is managing email templates.
The standard way to accommodate dynamic values is through the use of tokens, mapped (via model reflection) to attributes or microflows that allow for a replacement of data at runtime. This approach works great in most scenarios but presents a few limitations when working with:
- repeating sections (e.g. tables of information)
- conditional sections
- data formatting of token values
Working around these limitations is possible with the use of microflows that encapsulate the complexity e.g. building an HTML table that is stored in an attribute with a corresponding token. However, this abstracts some of the content and logic away from the template, which could have an impact on maintainability, and potentially forces a deployment for a minor content change.
This blog introduces a different method, using Handlebars.java, that allows you to define semantic templates and addresses the limitations described above.
{{ Handlebars.java }}
Handlebars.java (https://github.com/jknack/handlebars.java) is a java implementation of Mustache (http://mustache.github.io/mustache.5.html), providing a multi purpose template engine that allows you to define semantic templates.
Templates can be defined using syntax for the three most used implementations:
- Mustache.js (https://github.com/janl/mustache.js/)
- Hogan.js (http://twitter.github.io/hogan.js/)
- Handlebars.js (https://handlebarsjs.com/)
A template using this syntax consists of a series of tags, represented by a value contained within double curly brackets, e.g. {{tagName}}
A tag can be a variable name, can change the evaluation context (i.e. to access associated data) and can also apply helper functions to control things like conditionality, data transformation and data formatting.
AqHandlebars
We have created AqHandlebars, a simple Mendix module built on top of Handlebars.java that allows Mendix developers to use this template syntax in their app.
Data is provided to the template as a JSON object or a JSON array and the module handles the conversion of your template, returning a merged string.
So, given a domain model that looks like this:
We can represent data for an invoice in JSON as follows:
Building a template — standard functionality
We can access a root level property by name as follows:{{invoiceNumber}}
To access a nested property, we can either access it using dot-notation: {{customer.customerName}}
Or (useful if we want to access multiple properties) we can change the context before accessing the properties by name:
Adding repeating sections is the same syntax as changing the context:
There are three conditions available as standard, all three are only supported with boolean values.
Get Iain Lindsay’s stories in your inbox
Join Medium for free to get updates from this writer.
An if statement:
An if/else statement:
An unless statement (checks for a false value):
Re-using template snippets with partials
If there are sections of dynamic text that you want to use across multiple templates then you can define and reference partial templates.
So, a partial template with a name of ‘invoices’ and the following content:
Can then be referenced in my templates as follows: {{>invoices}}
Extending the syntax through custom helpers
The standard functionality already addresses some of the limitations described at the top of this article, however, we can take this further by extending the functionality supported by a template through the creation of custom helpers.
Custom helpers can be used for lots of different things, such as:
- checking value equality (extending conditional functionality)
- data formatting (formatting of dates, decimals etc.)
- data transformation (replacing values with html elements, such as transforming a link to an anchor tag)
To define a custom helper you need to create a Java class that implements the Helper interface from com.github.jknack.handlebars.
An example custom helper that transforms a value into an anchor tag is as follows:
AqHandlebars provides an additional interface, ICustomHelperRegister, that allows a Mendix application to register these helpers for use in templates.
An example implementation of this interface, using our custom helper above is:
The final step is to register this implementation via the Mendix front end:
And now, we can use this in our templates:{{anchor customer.website "tache"}}
Which produces this:<a href='https://www.handlebarclub.co.uk/'>tache</a>
Conclusion
Handlebars provides a powerful, semantic way to build dynamic string templates within your Mendix application.
The limitations with tokens described in the introduction can be addressed and the module is fully extensible to support whatever logic is required by your applications.
Tokens and Handlebars syntax are not, however, mutually exclusive. They can be used side by side so there is no need to rewrite existing templates; they can be adapted over time as required to support more complex scenarios.
Download the module today from app store and get templating!
Read more
From the Publisher -
If you enjoyed this article you can find more like it at our Medium page or at our own Community blog site.
For the makers looking to get started, you can sign up for a free account, and get instant access to learning with our Academy.
Interested in getting more involved with our community? You can join us in our Slack community channel or for those who want to be more involved, look into joining one of our Meet ups.
