Mapping the model to the template

The mapping file can contain a number of different mappings. This chapter will explain each mapping available.

Value

The value mapping is the simplest mapping. It creates a variable to use in the template by defining a name and an expression to calculate it:

<value name="component" eval="dataElement.component.name"/>

Expressions in mapping files are written in OGNL.

ConditionalValue

A conditionalValue will allow you to define a value which differs based on a set of conditions:

In this example, the value fileName can be overwritten by defining the option 'demo.filename'.

<conditionalValue name="fileName">
  <option if="dataElement.getOption('demo.fileName').defined" eval="dataElement.getOption('demo.fileName').value"/>
  <defaultOption eval="dataElement.name"/>
</conditionalValue>

A conditionalValue can contain multiple options. The expander will resolve the conditions top-down. Once a condition returns true, the value will be calculated with the eval expression.

Group

A group mapping will group values into an object. E.g. in this example the values in the group can be accessed in the template as <targetElement.packageName> and <targetElement.name>:

<group name="targetElement" if="field.linkField neq null">
  <value name="name" eval="field.linkField.targetElement.name"/>
  <value name="packageName" eval="field.linkField.targetElement.packageName"/>
</group>

An if condition can be added to only create the group if that condition is fulfilled.

List

The list mapping iterates over a collection and creates a list of mapped objects. It defines a param, which defines the name for the variable representing each object in the collection.

<list name="fieldTypes" eval="dataElement.fields" param="field">
  <!-- Filter records based on a predicate. You can have multiple filters. -->
  <filter name="isValueField" eval="field.valueField neq null"/>
  <!-- Remove all items that are duplicates based on the value presented in the eval. -->
  <distinct name="distinctTypes" eval="field.valueField.type"/> 
  <value name="name" eval="field.valueField.type.name"/>
</list>

A list can also define a filter and a unique expression. The filter will filter out all objects that do not match the condition.

The unique expression will filter out duplicates based on the result of the expression. E.g. unique="field.valueField.valueFieldType" will generate a list of objects that each have a unique valueFieldType.

Let

The let mapping does not have any direct effect on the template. Rather, it's used to define variables which can be used in other mappings.

See Extending the scope.

Assert

You can check if the model is valid by using asserts:

<assert name="versionField_isValueFieldType" message="Option `isVersion` can only be used in combination with a valueFieldType"
            eval="field.valueField neq null"/>

Include

Lastly, the include mapping will include another mapping file and add it to the mapping.

<include path="SomeCommonMapping.xml"/>
<!-- or -->
<include path="/path/to/SomeCommonMapping.xml"/>

Extended OGNL functionality

String formatting

A few attributes have been added to help with java.lang.String formatting.

Attribute	Example
.upper,.toUpper	dataElement to DATAELEMENT
.lower,.toLower	DataElement to dataelement
.firstToUpper	dataElement to DataElement
.firstToLower	DataElement to dataElement
.path,toPath	net.demo.package to net/demo/package
.kebab	dataElement to data-element
.camelCase	data_element to dataElement
.snakeCase	dataElement to data_element
.pascalCase	dataElement to DataElement

List helpers

The java.util.List class has been extended to provide the following commonly used operations.

Attribute	Description & Example
.exists(predicate)	List contains an element matching the predicate. dataElement.fields.exists(:[ #this.linkField neq null ]) "The dataElement has linkFields"
.notEmpty	List has one or more elements component.dataElements.notEmpty "component has dataElements"
.flatten	Flatten a List<List<T>> to List<T> application.components.{ dataElement }.flatten "get a list of dataElements in an application"

Lambda support

Ognl lambdas (:[ ... ]) can be used to define Function, Supplier and Predicate from the java.util.function package.

Class	Example
Function	optional.map(:[ #this.name ])
Supplier	optional.orElseGet(:[ #root.dataElement.name ])
Predicate	list.exists(:[ #this.getOption('option').defined ])