Skip to content

Expressions

Almost every tl:* attribute takes an expression as its value. This page is the complete reference for the expression language. Learn it once and it applies in tl:text, tl:if, tl:each, tl:attr, and everywhere else.

Variable expressions – ${...}

${...} reads a value from the rendering context. Paths use dot notation and traverse maps and objects null-safely:

<p tl:text="${user.name}">name</p>

Given the context {'user': {'name': 'Ada'}} this renders <p>Ada</p>.

Dynamic index access

Index into a list or map with a bracket expression:

<p tl:text="${items[index]}">item</p>

The index itself is an expression, so ${items[${i}]} and ${map['key']} both work.

Selection expressions – *{...}

Inside an element carrying tl:object, *{...} reads a field of the selected object directly, without repeating its name:

<div tl:object="${user}">
  <span tl:text="*{name}">name</span>
  <span tl:text="*{email}">email</span>
</div>

URL expressions – @{...}

@{...} builds a URL, optionally with query parameters supplied as name=${value} pairs in parentheses:

<a tl:href="@{/users(id=${userId})}">profile</a>

With userId = 42 this produces href="/users?id=42".

Message expressions – #{...}

#{...} looks up an internationalized message by key from a configured MessageSource. Positional arguments are passed in parentheses:

<p tl:text="#{welcome.title}">Welcome</p>
<p tl:text="#{greeting(${user.name})}">Hello, user!</p>

See Internationalization for wiring up a MessageSource.

String literals – '...'

Single-quoted text is a literal string:

<span tl:text="'Hello, world'">placeholder</span>

Literal substitution – |...|

Pipe-delimited text is a template string that interpolates embedded ${...} expressions, so you avoid manual concatenation:

<span tl:text="|Hello, ${name}!|">greeting</span>

Arithmetic

Numeric expressions support +, -, *, /, and %:

<span tl:text="${price} * ${quantity}">total</span>

String concatenation – +

The + operator concatenates strings (mixing in literals as needed):

<span tl:text="${first} + ' ' + ${last}">full name</span>

Ternary – ? :

A conditional expression chooses between two values:

<span tl:text="${active} ? 'Online' : 'Offline'">status</span>

Elvis – ?:

The Elvis operator supplies a default when the left side is null:

<span tl:text="${nickname} ?: 'Anonymous'">name</span>

Comparisons

Compare two values with ==, !=, <, >, <=, or >=:

<div tl:if="${score} >= ${passMark}">Passed</div>

Each operator also has a word-form alias, useful where symbols are awkward: eq (==), ne (!=), gt (>), lt (<), ge (>=), le (<=).

<div tl:if="${score} ge ${passMark}">Passed</div>

Boolean logic

Combine boolean expressions with and, or, and not (or !):

<div tl:if="${loggedIn} and not ${banned}">Welcome</div>

Filters – | name

A filter transforms a value using pipe syntax, and filters chain left to right:

<span tl:text="${name | upper}">NAME</span>
<span tl:text="${input | trim | lower}">cleaned</span>

Built-in filters: upper, lower, trim, length.

Filters take arguments with colon-separated syntax. Argument types include single-quoted strings, ints, doubles, bools, null, and bare identifiers:

<span tl:text="${price | currency:'USD':2}">price</span>
<span tl:text="${text | truncate:100}">long text</span>

Register custom filters when constructing the engine:

Trellis(filters: {
  'currency': (v) => '\$${(v as num).toStringAsFixed(2)}',
  'truncate': (v, [args]) {
    final limit = (args?.firstOrNull as int?) ?? 80;
    final s = v.toString();
    return s.length <= limit ? s : '${s.substring(0, limit)}…';
  },
});

Utility objects – ${#...}

Built-in utility objects expose common helpers for strings, numbers, dates, and lists:

<span tl:text="${#strings.capitalize(name)}">Name</span>
<span tl:text="${#lists.size(items)}">count</span>

The available objects are ${#strings.*}, ${#numbers.*}, ${#dates.*}, and ${#lists.*}.

No-op – _

A bare underscore means "do nothing" – it preserves the prototype value and is handy in a ternary that should sometimes leave an attribute untouched:

<a tl:attr="aria-current=${isActive} ? 'page' : _">Link</a>

Quick reference

Form Example Meaning
Variable ${user.name} Read from context, dot-notation, null-safe
Dynamic index ${list[index]} List/map access with an expression index
Selection *{field} Field of the tl:object context
URL @{/users(id=${id})} URL with query parameters
Message #{welcome.title} i18n key lookup via MessageSource
String literal 'hello' Single-quoted string
Literal substitution |Hi, ${name}!| Pipe-delimited interpolated string
Arithmetic ${a} + ${b} (- * / %) Numeric arithmetic
Concatenation ${a} + ' ' + ${b} String concatenation
Ternary ${c} ? 'a' : 'b' Conditional value
Elvis ${v} ?: 'default' Null-coalescing
Comparison ${a} == ${b} (!= < > <= >=) Value comparison
Comparison alias gt lt ge le eq ne Word-form comparison operators
Boolean ${a} and ${b} (or, not / !) Logical operators
Filter ${name | upper} Pipe-based value transformation
Utility object ${#strings.capitalize(x)} Built-in string/number/date/list helpers
No-op _ Explicitly do nothing