TemplateExpressions define the rendering for model objects. The template syntax is defined as follows:

Literal text

All text is interpreted as literal (internationalized) text, except for embedded template expressions, see blow.

Template expression

A template expression is surrounded with braces { [expr] }.

Literal XML/HTML

XML/HTML structure can be output literally with embedded expressions in attribute values and tag content: <div class="myclass {$other}">Some {$value}.</div>.

Template reference

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.

Conditional evaluation

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.

Alternative evaluation

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] }.

Embedded template text

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} }

Property access

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.

Variable access

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.

Function call

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().

Iteration

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".

Indexed access

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.

Map access

If an accessed value is map-valued with string keys, an element with some key may be accessed with $my-var['some-key'].

Reference access

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}.

Literal string

A literal string (without the possibility of embedding further expressions) is written as 'some text', or "some text".

Literal numbers

A literal integral value is simply written as number 42.

Access to the underlying model object

The underlying model as whole can be referenced by the keyword this.

HTML output

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>