Overview

Documentation

AqHandlebars

Module based on Handlebars.java (https://github.com/jknack/handlebars.java), 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:

1. Mustache.js (https://github.com/janl/mustache.js/)
2. Hogan.js (http://twitter.github.io/hogan.js/)
3. 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.

Template Data

Data to be used alongside a template must be formatted as JSON.

JSON data can be generated by the module using an export mapping or can be provided within a string parameter.

The module supports both JSON Objects and JSON Arrays

Accessing data

Variable access

Variables can be accessed by name (when a member of the current context)

{{variableName}}

Variables can be accessed by dot-notation (when a child member of the current context)

{{nestedObject.variableName}}

Changing the context

The context can be changed to access a nested object or array of objects

{{#nestedObject}}
{{variableName}}
{{/nestedObject}}

When passing a JSON array into the module, you can access the elements using the following

{{#.}}
{{variableName}}
{{/.}}

HTML

HTML is escaped by default. To output the raw HTML, use three curly braces

{{{variableName}}}

Conditions

Standard conditions can only be applied to boolean values

if

{{#if booleanVariable}}
I'll only be shown if true
{{/if}}

if / else

{{#if booleanVariable}}
I'll only be shown if true
{{else}}
I'll only be shown if false
{{/if}}

unless

{{#unless booleanVariable}}
I'll only be shown if false
{{/unless}}

Partial Templates

Re-usable sections of a template (similar to Snippets), called Partial Templates can be maintained via the PartialTemplate_Overview page

A partial template can then be referenced in a template like this

{{>partialTemplateName}}

All the generation actions within the module can receive an optional list of PartialTemplate objects, allowing you to control what partials are used with which templates

Custom Helpers

Custom helpers can be built to extend the functionality of the module.

Creating and using a custom is a 4 step process

1. Create a helper class

Please refer to http://jknack.github.io/handlebars.java/helpers.html for information on creating custom helpers

2. Create/extend a helper register class

AqHandlerbars provides an interface, ICustomHelperRegister, that exposes a single method, registerCustomHelpers.

You will need to create a concrete implementation of this interface in order to register the helpers created in step 1

Note, that you can create as many concrete classes as you want, allowing you to break down registrations (e.g. by category) if required

registerCustomHelpers can use either method for registering a helper (i.e. a single helper via handlebars.registerHelper() or multiple helpers using a HelperSource via handlebars.registerHelpers(). Please refer to http://jknack.github.io/handlebars.java/helpers.html for details

3. Create a helper register object via the Mendix front end

Once you have created your concrete class you can register it via the CustomHelperRegister_Overview page. Each object requires just two properties, a user friendly name and the fully qualified name of the class

4. Update your templates to utilise the new helper

You can now use your helpers in your templates.

When using any of the 'Generate...' java actions, each CustomHelperRegister object created via the Mendix front end will be executed prior to processing your template

Generating from templates

Five java actions are available to generate a string based on a template.

GenerateForExportDocumentAndObject

Generates a string based on a template, an export mapping document and an object that represents the root for the export mapping

(useful where the export mapping is known at design time)

GenerateForExportDocumentAndObjectList

Generates a string based on a template, an export mapping document and a list of objects that represents the root for the export mapping

(useful where the export mapping is known at design time

GenerateForExportNameAndObject

Generates a string based on a template, the name of an export mapping document and an object that represents the root for the export mapping

(useful where the export mapping is known at run time, e.g. via a configuration object)

GenerateForExportNameAndObjectList

Generates a string based on a template, the name of an export mapping document and a list of objects that represents the root for the export mapping

(useful where the export mapping is known at run time, e.g. via a configuration object)

GenerateForJSONString

Generates a string based on a template, using a JSON object/array provided in a string parameter

(useful where the data is dynamic)