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 and no new expression syntax:
tl:slot– the caller hands markup to named regions of the fragment.tl:attrs="${map}"– spread a map onto an element as attributes (reference)....restparameter – a trailing fragment parameter that receives the attributes written on the invoking element.
Both the component file and the template that uses it stay valid HTML, so each opens in a browser as a prototype.
The examples on this page are executed by the Trellis test suite. Each
file=fence is a template in the page's loader, eachrender=fence is rendered with thecontext=JSON beside it, and the result is checked against theoutput=fence. Output whitespace is collapsed for display.
A component and its use
The component file declares parameters, a rest parameter and two slots:
<label tl:fragment="field(label, name, ...attrs)" class="field">
<span class="field-label" tl:text="${label}">Label</span>
<input class="field-input" type="text" tl:attr="name=${name}" tl:attrs="${attrs}">
<span class="field-hint" tl:slot="hint"></span>
</label>
<dialog tl:fragment="dialog(id, title, ...attrs)" class="dialog" tl:id="${id}" tl:attrs="${attrs}">
<header><h2 tl:text="${title}">Title</h2></header>
<div class="dialog-body" tl:slot>Body</div>
<footer tl:slot="footer"><button>Close</button></footer>
</dialog>
The page invokes them with tl:replace:
<div tl:replace="~{ui/field.html :: field('Email', 'email')}"
type="email" required hx-post="/validate" hx-trigger="blur">
<span tl:slot="hint">We never share your email.</span>
</div>
<div tl:replace="~{ui/dialog.html :: dialog('confirm', 'Delete item?')}">
<p>This action cannot be undone.</p>
<tl:block tl:slot="footer">
<button tl:attr="hx-delete=@{/items(id=${item.id})}">Delete</button>
<button>Cancel</button>
</tl:block>
</div>
{"item": {"id": 7}}
<label class="field">
<span class="field-label">Email</span>
<input class="field-input" type="email" required="" hx-post="/validate" hx-trigger="blur" name="email">
<span class="field-hint">We never share your email.</span>
</label>
<dialog class="dialog" id="confirm">
<header><h2>Delete item?</h2></header>
<div class="dialog-body"><p>This action cannot be undone.</p></div>
<footer>
<button hx-delete="/items?id=7">Delete</button>
<button>Cancel</button>
</footer>
</dialog>
The type, required and hx-* attributes written on the host landed on the
<input> inside the component, and the caller's text replaced the hint's empty
fallback.
Content slots – tl:slot
Defining slots
Inside a fragment, any element may carry tl:slot="name". Its children are the
fallback content. A bare tl:slot marks the single anonymous (default)
slot. Each slot name may be declared once per fragment, and the fragment's own
root element cannot be a slot: declare the region on an inner element.
A region may carry its own directives. When the caller fills the region, its
tl:text, tl:utext, tl:insert and tl:replace are dropped so the caller's
content shows. Unfilled, they render as the default, which suits a slot that
falls back to a parameter. tl:if, tl:each and tl:attr apply either way.
<div tl:fragment="popover(label)" class="popover">
<button tl:slot="trigger" tl:text="${label}">Open</button>
<div class="popover-body" tl:slot>Details</div>
</div>
<div tl:replace="~{ui/popover.html :: popover('Menu')}"></div>
<div tl:replace="~{ui/popover.html :: popover('Menu')}">
<i tl:slot="trigger">Custom</i>
</div>
<div class="popover"><button>Menu</button><div class="popover-body">Details</div></div>
<div class="popover"><button>Custom</button><div class="popover-body">Details</div></div>
Filling slots
The direct children of the element carrying tl:insert or tl:replace
provide the content:
- A direct child with
tl:slot="name"fills the slot of that name. Several markers for the same slot concatenate in document order. - Unmarked children fill the anonymous slot, if the fragment declares one. Otherwise they are discarded, as invocation placeholders always have been.
- Whitespace-only text never counts as unmarked content (ASCII whitespace only:
a child holding just
is content), and neither do HTML comments, so a pretty-printed call that fills only named slots keeps the anonymous slot's fallback. - A slot with no marker keeps its fallback. A marker with no children clears it.
<article tl:fragment="card(title)" class="card">
<h3 tl:text="${title}">Title</h3>
<div class="card-body" tl:slot>Default body</div>
<footer tl:slot="footer">Default footer</footer>
</article>
<div tl:replace="~{ui/card.html :: card('A')}"></div>
<div tl:replace="~{ui/card.html :: card('B')}"><p>Body text</p></div>
<div tl:replace="~{ui/card.html :: card('C')}">
<b tl:slot="footer">Only the footer</b>
</div>
<div tl:replace="~{ui/card.html :: card('D')}">
<i tl:slot="footer">one</i>
<i tl:slot="footer">two</i>
</div>
<article class="card"><h3>A</h3><div class="card-body">Default body</div><footer>Default footer</footer></article>
<article class="card"><h3>B</h3><div class="card-body"><p>Body text</p></div><footer>Default footer</footer></article>
<article class="card"><h3>C</h3><div class="card-body">Default body</div><footer>Only the footer</footer></article>
<article class="card"><h3>D</h3><div class="card-body">Default body</div><footer>onetwo</footer></article>
The merge model: the marker is discarded
A slot fills like a tl:define block override
(inheritance): the region element in the fragment
is kept and only its children are replaced. The caller's marker element is
discarded and its children move in. In case C above the <b> is gone and
<footer> holds its text.
This differs from the web-component <slot> you may know, where the filler
element itself is projected into the slot. To contribute several elements with
no wrapper, use <tl:block tl:slot="name"> (not inside a table, see below).
Scope: slot content sees the fragment's variables
Slot content is grafted into the fragment before it is processed, so it sees the fragment's variables: the caller's context plus the fragment's parameters and locals. A fragment parameter shadows a same-named caller variable inside slot content:
<div tl:replace="~{ui/card.html :: card('Fragment title')}">
<p><span tl:text="${title}">x</span></p>
</div>
{"title": "Caller title"}
<article class="card"><h3>Fragment title</h3><div class="card-body"><p><span>Fragment title</span></p></div><footer>Default footer</footer></article>
The same rule makes a scoped slot work: a tl:slot region inside the
fragment's own tl:each is cloned per iteration, and the caller's markup sees
the loop variable.
<table>
<tbody tl:fragment="table(rows)">
<tr tl:each="row : ${rows}" tl:slot="row"><td tl:text="${row.name}">Name</td></tr>
</tbody>
</table>
<table>
<tbody tl:replace="~{ui/table.html :: table(${people})}">
<tr tl:slot="row"><td tl:text="${row.name}">Name</td><td>!</td></tr>
</tbody>
</table>
{"people": [{"name": "Ada"}, {"name": "Grace"}]}
<table>
<tbody>
<tr><td>Ada</td><td>!</td></tr>
<tr><td>Grace</td><td>!</td></tr>
</tbody>
</table>
Which element can be a marker
The HTML5 parser reshapes a document before Trellis sees it, so a marker must be
an element the parser accepts as a child of the host: <tr> and <td> only
when the host sits inside a real <table> (as above), <option> when the host
is a <select>, and <span>, <tl:block> and most other elements everywhere
else. This is an authoring rule, not a runtime check. To fill a <select> from a
non-select host, mark an <optgroup tl:slot> holding real <option> elements.
Definition-side regions can be <tr> or <option> freely, because they already
sit in table or select context.
The parser also wraps <tr> children of a <table> in an implicit <tbody>. A
<tr tl:slot> written directly under a <table> host is therefore not a direct
child, and its fill is lost. <thead>, <tbody>, <tfoot>, <caption> and
<colgroup> markers need a <table> host: under a <div> host the parser drops
them. So a table component that takes a header and rows in one call declares a
region per section, and the caller marks whole sections:
<table tl:fragment="data-table(rows)" class="data-table">
<thead tl:slot="head"><tr><th>Name</th></tr></thead>
<tbody tl:slot="body"><tr tl:each="row : ${rows}"><td tl:text="${row.name}">Name</td></tr></tbody>
</table>
<table tl:replace="~{ui/data-table.html :: data-table(${people})}">
<thead tl:slot="head"><tr><th>Person</th></tr></thead>
</table>
<table tl:replace="~{ui/data-table.html :: data-table(${people})}">
<tbody tl:slot="body"><tr><td>Fixed</td></tr></tbody>
</table>
{"people": [{"name": "Ada"}, {"name": "Grace"}]}
<table class="data-table">
<thead><tr><th>Person</th></tr></thead>
<tbody><tr><td>Ada</td></tr><tr><td>Grace</td></tr></tbody>
</table>
<table class="data-table">
<thead><tr><th>Name</th></tr></thead>
<tbody><tr><td>Fixed</td></tr></tbody>
</table>
To repeat a caller row per item, as in the scoped-slot example above, make the
host a <tbody> inside the page's own <table> and mark <tr> children.
Nested regions
A tl:slot inside another region's fallback is part of that fallback, not a
second declaration. A caller marker can therefore not name the inner slot, and
filling the outer slot removes the inner one with the rest of the fallback.
Gating a marker with tl:if / tl:unless
tl:if and tl:unless on a caller-side marker decide whether it contributes. A
falsy gate contributes nothing, and the slot keeps its fallback if no other
marker fills it.
<div tl:replace="~{ui/card.html :: card('G')}">
<b tl:slot="footer" tl:if="${showFooter}">Shown</b>
</div>
{"showFooter": false}
<article class="card"><h3>G</h3><div class="card-body">Default body</div><footer>Default footer</footer></article>
The gate is evaluated when the content is grafted, before the fragment
processes its own tl:each, so a loop variable of the fragment does not exist
yet. Gating a marker on one throws in strict mode:
<table>
<tbody tl:replace="~{ui/table.html :: table(${people})}">
<tr tl:slot="row" tl:if="${row.name == 'Ada'}"><td>Ada only</td></tr>
</tbody>
</table>
{"people": [{"name": "Ada"}]}
Undefined variable: "row"
Gate on caller-side data, or put the condition inside the slot content.
Errors
These throw TemplateException, and a marker is checked before its tl:if or
tl:unless runs, so a mistake fails regardless of the data:
<div tl:replace="~{ui/card.html :: card('H')}"><b tl:slot="sidebar">x</b></div>
targets a slot fragment "card" does not declare
<div tl:replace="~{ui/field.html :: field('Name', 'name')}"><b tl:slot>x</b></div>
targets the anonymous slot, which fragment "field" does not declare
Unmarked children draw no error when there is no anonymous slot, but a bare
tl:slot marker does, because a marker states an intent to fill. Any other
tl:* attribute on a marker throws, so a replicated contribution via tl:each
is not available:
<div tl:replace="~{ui/card.html :: card('I')}">
<b tl:slot="footer" tl:each="x : ${xs}">x</b>
</div>
{"xs": [1, 2]}
only tl:if and tl:unless may accompany tl:slot
A duplicate slot name in one fragment, tl:slot on the tl:fragment element
itself, and a tl:slot in the unmarked content of an inner host inside a
definition (below) also throw when the fragment
is invoked.
Slots, like the rest parameter, work through name-based invocation only.
~{file :: #id} and tag-name targets never bound parameters, and a marker on
such an invocation throws the unknown-slot error. A tl:slot outside any
fragment is inert: the attribute is dropped and the content stays.
A marker must be a direct child of the host
Only literal direct children count. On a page, a marker nested deeper, or inside
a <tl:block> wrapper, is not looked through: it is inert and its container
becomes unmarked content. Inside a fragment definition the same shape is an
error, see Composing slotted fragments.
<div tl:replace="~{ui/dialog.html :: dialog('d', 'Title')}">
<div><span tl:slot="footer">Never bound</span></div>
</div>
<dialog class="dialog" id="d">
<header><h2>Title</h2></header>
<div class="dialog-body"><div><span>Never bound</span></div></div>
<footer><button>Close</button></footer>
</dialog>
TemplateValidator warns about this mistake, see Validation.
Composing slotted fragments
A fragment can invoke another from inside its own definition. A marker binds to
its nearest enclosing host, so the direct-child markers of the inner host are
that invocation's contribution, not slots of the outer fragment. To pass a slot
through, re-mark it: put a tl:slot region inside the contribution. The
outer fragment then declares it, and its caller fills it as usual. A bare
<tl:block tl:slot> contribution forwards its content into the inner fragment's
anonymous slot the same way:
<section tl:fragment="confirm(title)" class="confirm">
<div tl:replace="~{ui/dialog.html :: dialog('confirm', ${title})}">
<tl:block tl:slot>
<p tl:slot="message">Are you sure?</p>
</tl:block>
<tl:block tl:slot="footer">
<span tl:slot="actions"><button>OK</button></span>
</tl:block>
</div>
</section>
<div tl:replace="~{ui/confirm.html :: confirm('Delete item?')}">
<p tl:slot="message">This cannot be undone.</p>
<tl:block tl:slot="actions"><button>Delete</button><button>Cancel</button></tl:block>
</div>
<div tl:replace="~{ui/confirm.html :: confirm('Archive item?')}"></div>
<section class="confirm">
<dialog class="dialog" id="confirm">
<header><h2>Delete item?</h2></header>
<div class="dialog-body"><p>This cannot be undone.</p></div>
<footer><span><button>Delete</button><button>Cancel</button></span></footer>
</dialog>
</section>
<section class="confirm">
<dialog class="dialog" id="confirm">
<header><h2>Archive item?</h2></header>
<div class="dialog-body"><p>Are you sure?</p></div>
<footer><span><button>OK</button></span></footer>
</dialog>
</section>
A tl:slot that sits in the unmarked content of the inner host, wrapped in
some other element, is neither: it is not a direct child, so it cannot fill the
inner slot, and nothing says it should declare a slot of the outer fragment.
Rather than guess, the engine throws when the outer fragment is invoked, filled
or not, and even when the inner invocation is gated off by tl:if. The message
names the marker, the host directive and the fragment, and points at the two
fixes: make the marker a direct child of the host, or re-mark it inside a
direct-child marker.
<section tl:fragment="confirm">
<div tl:replace="~{ui/dialog.html :: dialog('c', 'Title')}">
<p><i tl:slot="footer">OK</i></p>
</div>
</section>
<div tl:replace="confirm"></div>
is inside the unmarked content of a tl:replace host
A host nested in that unmarked content starts over for its own children, and a
nested tl:fragment owns its own slots. On a page there is no enclosing
fragment to declare anything, so a wrapped marker stays inert and only draws a
validator warning.
Attribute spreading – tl:attrs
tl:attrs="${map}" writes every entry of a map as an attribute, with the merge
rules documented in the attributes reference. It is
how a component places the attributes it receives.
Pass-through – the ...rest parameter
A fragment opts in to receiving the invoking element's attributes by declaring a rest parameter, at most one and always last:
<span tl:fragment="chip(label, ...attrs)" class="chip" tl:attrs="${attrs}" tl:text="${label}">Label</span>
At invocation the engine binds it to a map of the host's effective attribute
set: its literal attributes plus the results of its own attribute directives
(tl:attr, the shorthands, tl:classappend and tl:styleappend, and
tl:attrs), evaluated once in the caller's scope, minus every tl:* control
attribute. The fragment decides where the map goes. Valueless booleans arrive as
empty strings and render valueless again. Values are opaque strings, so hx-* and
data-* attributes pass through without the core knowing about them.
<a tl:replace="~{ui/chip.html :: chip('New')}" class="big" data-id="1"
tl:classappend="${tone}" tl:attrs="${extra}"></a>
{"tone": "hot", "extra": {"hx-get": "/new"}}
<span class="chip big hot" data-id="1" hx-get="/new">New</span>
Prefer tl:replace for components
With tl:replace the host element disappears, so forwarding its attributes is
the only way they survive. With tl:insert the host stays, applying its own
attribute directives, and the same map is also bound, so spreading it repeats
the attributes on the surviving host. tl:insert also keeps only the fragment
root's children, so a tl:attrs spread or ...rest on the fragment root is
not visible under tl:insert. Spread on an inner element instead:
<div tl:fragment="link(href, ...attrs)"><a tl:href="${href}" tl:attrs="${attrs}">Open</a></div>
<section tl:insert="~{ui/link.html :: link('/x')}" class="host"></section>
<section class="host"><a class="host" href="/x">Open</a></section>
Rules
- A rest parameter that is repeated, not last, unnamed or named like a
positional parameter throws when the fragment definition is collected.
Whitespace after
...is ignored, so... attrsdeclaresattrs. - An invocation with more positional arguments than the declared non-rest parameters throws. Fragments without a rest parameter keep ignoring extras.
renderFragment()binds the rest parameter to an empty map, see rendering a fragment as a response.
<div tl:replace="~{ui/field.html :: field('Email', 'email', 'extra')}"></div>
takes 2 positional argument(s) before its rest parameter
Spread the map, do not probe it
In strict mode, reading a key the map lacks throws before an elvis or ternary can
apply a default, and filters take one argument. A component therefore spreads the
whole map and keeps its defaults as literal attributes that the spread
overwrites, as field does with type="text".
<span tl:fragment="probe(...attrs)" tl:text="${attrs.type} ?: 'text'">x</span>
<div tl:replace="~{ui/probe.html :: probe}"></div>
Undefined member: "type"
Traps and conventions
| Trap | What happens | Do this |
|---|---|---|
| Slot content shadowing | A fragment parameter hides a same-named caller variable inside slot content | Name parameters distinctly, or pass the value as an argument |
| Self-nesting | A component inside its own slot content trips the name-keyed fragment cycle error | Restructure, or invoke a differently named fragment |
<tl:block tl:slot> in a table |
The HTML5 parser foster-parents <tl:block> out of <table>, detaching its tl:* attributes |
Mark a real element: <tr> or <td> |
| Directive on a filled region | A region's own tl:text, tl:utext, tl:insert and tl:replace are dropped when the caller fills it |
Expect the caller's content to win; put a default there only to show when unfilled |
<tr tl:slot> under a <table> host |
The parser wraps the rows in an implicit <tbody>, so they are not direct children and the fill is lost |
Mark <tbody tl:slot>, or host on a <tbody> |
| Marker timing | tl:if on a marker runs before the fragment's tl:each |
Gate on caller data |
| Dynamic attribute names | tl:attrs is the first place a name, not only a value, is decided at runtime |
Names are validated and tl:-prefixed keys throw, but never build the map from untrusted keys |
| Mixed-case keys | Class or ID replaces the existing class or id instead of appending |
Write spread keys lowercase; only the exact keys class and style append |
data-* camel case |
HTML parsers lowercase attribute names, so data-myFoo never reaches dataset.myFoo |
Use lowercase names |
| Custom dialects | slot and attrs are now built-in tl:* names; a dialect processor registered under either name runs alongside the built-in slot or spread handling, silently |
Rename the custom attribute |
The self-nesting case, for reference:
<div tl:replace="~{ui/card.html :: card('Outer')}">
<div tl:replace="~{ui/card.html :: card('Inner')}">inner</div>
</div>
Fragment cycle detected
Validation
TemplateValidator (and dart run trellis:validate) reports these composition
mistakes:
- A
tl:slotmarker under a visibletl:insert/tl:replacehost that is not the host's literal direct child. On a page it can never bind, so this is a warning. Inside a fragment definition it is an error with the engine's message, see Composing slotted fragments; a marker inside one of the host's direct-child markers re-marks a region and is clean. A marker with no host in the same document is assumed to be a definition-side region and is not reported. The error is reported for a wrapped marker inside any fragment definition, because invoking it by name throws, even where the definition is only rendered inline, byrenderFragmentor by selector, which leave the marker inert. - A literal
idon or inside a parameterized fragment (a warning). The fragment may render several times on one page, repeating the id. Set it per use withtl:idortl:attrs. Parameterless fragments are the usual HTMX swap-target pattern (tl:fragment="todo-list"around<div id="todo-list">) and never warn; a literalidthattl:idor atl:attridbinding overrides is a prototype placeholder and does not warn either.
The id check skips markup the render discards: an element carrying tl:replace
(its own id), anything under tl:remove="all", and the children of a
tl:text or tl:utext element that replaces them (tl:text="_" is a no-op
that keeps them, so they are checked). A tl:replace or tl:insert host's own
children are discarded too, except the content of its direct-child tl:slot
markers, which renders in the invoked fragment and is checked. An element that
survives (a tl:insert host, a tl:text element) keeps its own id in the
check. Not checked: a host's unmarked children, which render only when the
invoked fragment declares an anonymous slot, and one file does not show that.
One shape still warns although the id never repeats: a parameterized swap
target with a literal root id. Move the id to tl:id or make the fragment
parameterless.
isValidTemplate() treats warnings as failures, and dart run trellis:validate --strict
exits non-zero on them.