TemplateExpressions define the rendering for model objects. The template syntax is defined as follows:
All text is interpreted as literal (internationalized) text, except for embedded template expressions, see blow.
A template expression is surrounded with braces { [expr] }.
XML/HTML structure can be output literally with embedded expressions in attribute values and tag content: <div class="myclass {$other}">Some {$value}.</div>.
In a template expression, another template can be referenced by its name {-> [other-template]}. In the output, a template reference is replaced by the expansion of the referenced template based on the same configuration instance.
A template expression can consist of a conditional evaluation operator { [test] ? [if] : [else] }. When evaluated, the conditional expression evaluates to the expansion of the [if] expression, if the expression [test] evaluates to a non-null, non-zero, or non-empty value. Otherwise, the [else] expression is evaluated.
To create an alternative representation for an otherwise empty value, a short-cut form for { [alternative1] ? [alternative1] : [alternative2] } is possible through an alternative expression { [alternative1] | [alternative2] }.
Within a template expression, the parser mode can be switched back to literal text (with potentially embedded template expressions) by surrounding the literal text again with braces { [test] ? {some literal text} : {some other literal text} }
Access to the value of a model property of the underlying model object is done by using the property name {my-property}.
Accessing a property that is not defined by the underlying model results in an error.
By default, properties of ConfigurationItem models can be accessed using their property name. When using a com.top_logic.layout.template.TLModelAccess for evaluation, persistent objects (com.top_logic.model.TLObject) and arbitrary objects implementing the com.top_logic.layout.template.WithProperties interface can also be accessed.
In the actual evaluation context, a set of variables may be defined (as key value mapping). Such variable can be accessed by its name by prepending a $ sign. A variable with name my-var may be accessed with $my-var.
Globally defined functions can be invoked from template expressions. A function is referenced through a # prefix to its name. The function sublist is e.g. invoked through the expression #sublist($l, 2), where the first argument is expected to reference a list value and the second gives the start offset as integer value. For all defined functions, see the configuration of GlobalConfig#getFunctions().
If an accessed value is list-valued, all values may be iterated with e.g. {foreach(x : $my-var, '; ', {"{$x}"})}. This binds each value of the list value $my-var to the locally-defined variable $x and evaluates the template "{$x}" for each list element (effectively dumping each element surrounded by double quotes). Between two evaluations, the separator expression '; ' expands to a semicolon followed by a space. If the value of $my-var is the list of numbers 1, 2, 3, the final evaluation result would be "1"; "2"; "3".
If an accessed value is list-valued, an element at some index may be accessed with $my-var[42].
Accessing an out-of range index results in a null value. This allows e.g. for testing, whether a collection contains a certain number of entries through {list[1] ? ...}.
Accessing with a negative index has the semantics of accessing with an index relative to the end of the list. For a list with size 5, the expression {list[-2]} evaluates to the element at index 3.
If an accessed value is map-valued with string keys, an element with some key may be accessed with $my-var['some-key'].
If an accessed value is a configuration value itself, a specific property may be accessed using a dot-separated path expression {$my-var.some-property}.
A literal string (without the possibility of embedding further expressions) is written as 'some text', or "some text".
A literal integral value is simply written as number 42.
The underlying model as whole can be referenced by the keyword this.
When output is generated through a com.top_logic.layout.template.TemplateWriter, the template can contain embedded HTML syntax. The HTML may contain embedded expressions within attribute or element content:
<div class="{my-class}">{my-text}</div>