Skip to content

Syntax Reference

This is the complete reference for the Trellis template language. It documents every tl:* attribute the engine ships with, the <tl:block> virtual element, and every expression form you can write inside an attribute.

If you are new to Trellis, read Getting Started first, then come back here to look things up.

Expression language

The value of nearly every tl:* attribute is an expression. Learn the expression syntax once and it applies everywhere.

  • Expressions – variables ${...}, selection *{...}, URLs @{...}, messages #{...}, literals, arithmetic, ternary, Elvis, comparisons, boolean logic, filters, utility objects, and the no-op.

Attributes by group

Processing order

When several attributes appear on one element, the engine applies them in a fixed priority order, highest first:

  1. tl:with – bind local variables
  2. tl:object – set the selection context
  3. tl:if / tl:unless – conditionals
  4. tl:switch / tl:case – multi-branch conditionals
  5. tl:each – iteration
  6. tl:insert / tl:replace – fragment inclusion
  7. tl:text / tl:utext – content
  8. tl:attr and the attribute shorthands – attribute mutation. Within this group tl:attrs (spread) runs first, so the other attribute directives override its entries.

tl:slot is not a processing step: it is resolved while a fragment is included (step 6) and holds no place in this order.

Understanding this order explains, for example, why tl:if on the same element as tl:each is evaluated before the loop runs.

  • 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…

  • Text

    Two attributes replace an element's body with a value: tl:text escapes the result, and tl:utext inserts it as raw HTML.

  • Conditionals

    Trellis has two conditional mechanisms: tl:if / tl:unless for a single boolean test, and tl:switch / tl:case for multi-branch selection.

  • Iteration

    tl:each repeats an element once per item in a collection.

  • Attributes

    Trellis can set any HTML attribute from an expression. There is one generic attribute, tl:attr, plus convenient shorthands for the most common cases.

  • Fragments

    Fragments are named, reusable pieces of a template. They are the foundation of Trellis's HTMX-first design: the same fragment renders inside a full page…

  • Composition

    A component in Trellis is a fragment that accepts parameters, content and extra attributes from its caller. Three primitives provide that, with no new elements…

  • Template Inheritance

    Template inheritance lets a page build on a shared layout, overriding named blocks. It is the layout-composition counterpart to fragments.

  • Local Variables & Selection

    Two attributes shape the data available to an element and its children: tl:with binds named local variables, and tl:object sets a selection context for *{...}…

  • Inline Processing

    tl:inline enables inline expression syntax inside an element's text content, so you can interpolate values without wrapping every one in its own…

  • Output Control

    These two features control what actually reaches the output HTML: tl:remove strips elements or their tags, and &lt;tl:block&gt; groups content without emitting…

  • Internationalization

    Trellis supports internationalized messages through #{...} message expressions backed by a MessageSource.