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 and,
via renderFragment(), as a standalone partial response.
tl:fragment – define a fragment
tl:fragment names an element as a reusable fragment. Fragments can take
parameters, listed in parentheses:
<div tl:fragment="card(title, body)">
<h2 tl:text="${title}">Title</h2>
<p tl:text="${body}">Body</p>
</div>
tl:insert – include, keeping the host element
tl:insert renders a fragment inside the host element, which is preserved.
Arguments are passed positionally to a parameterized fragment:
<div tl:insert="card('Hello', 'World')">replaced by fragment</div>
tl:replace – include, replacing the host element
tl:replace renders the fragment in place of the host element, which is
discarded:
<div tl:replace="userCard">replaced entirely</div>
Cross-file inclusion
Reference a fragment in another template file with the ~{file :: fragment}
syntax:
<div tl:insert="~{components :: header}">loads header from components.html</div>
CSS-selector targeting
Instead of a fragment name, target an element in another file by #id or
.class:
<div tl:insert="~{components :: #main-nav}">loads by id</div>
In the same file, tl:insert="#main-nav" and a bare tag name (tl:insert="footer",
when no fragment has that name) work too. The target is copied as written in the
template, not as rendered, and evaluated with the host's variables. Inside a
fragment included from another file, such a target is looked up in that file
first, then in the page, the same order as a fragment name. A bare tag name is
tried only when no fragment of that name exists in either.
Circular fragment inclusions are detected and reported with the full cycle path.
Components
Fragments can also take content and extra attributes from the caller, through
tl:slot, tl:attrs and a trailing ...rest parameter. See
Composition. Those work through name-based
invocation only (tl:replace="~{file :: name(...)}"), not CSS-selector targeting.
Rendering a fragment directly
From Dart, render just a named fragment – this is what an HTMX partial response returns:
final fragment = engine.renderFragment(
pageTemplate,
fragment: 'itemList',
context: {'items': items},
);
Rendering a parameterised fragment as a response
renderFragment, renderFragments, renderFileFragment and renderFileFragments
(and the Shelf, dart_frog and Relic helpers and the testing helpers built on them)
address a fragment by its bare name, even when it declares parameters. A
fragment declared toast(type, title) is rendered with fragment: 'toast', and
its parameters resolve from the same-named keys of the render context, like any
other variable:
<div tl:fragment="toast(type, title)" class="toast" tl:classappend="${type}">
<strong tl:text="${title}">Title</strong>
</div>
{"type": "error", "title": "Saved"}
<div class="toast error"><strong>Saved</strong></div>
An absent key is null, or throws in strict mode, as for any variable. A ...rest
parameter is bound to an empty map, so a component that spreads it renders in
strict mode too. The result is fully processed.
An out-of-band toast
htmx swaps out of band only an element that carries hx-swap-oob. Put that
attribute on a thin wrapper, not on the toast's own root: the root is also what
every in-page tl:replace="toast(…)" renders, and inside an htmx response an
in-page toast carrying hx-swap-oob would be pulled out of the main swap. Keep
each wrapper thin: it declares the toast's parameters, carries only hx-swap-oob
(and an id where the swap needs one), and invokes toast with them, so all toast
markup stays in the one definition.
A stacking swap such as beforeend needs the wrapper anyway, because htmx 2
inserts only the children of a non-outerHTML out-of-band element:
<div tl:fragment="toast(type, title)" class="toast" tl:classappend="${type}">
<strong tl:text="${title}">Title</strong>
</div>
<div tl:fragment="toastStack(type, title)" hx-swap-oob="beforeend:#toasts">
<div tl:replace="toast(${type}, ${title})"></div>
</div>
{"type": "error", "title": "Saved"}
<div hx-swap-oob="beforeend:#toasts"><div class="toast error"><strong>Saved</strong></div></div>
For an outerHTML swap by id, the wrapper takes the id of the element it
replaces as a parameter and sets it with tl:id, since a literal id repeats on
every render:
<div tl:fragment="toast(type, title)" class="toast" tl:classappend="${type}">
<strong tl:text="${title}">Title</strong>
</div>
<div tl:fragment="toastById(id, type, title)" tl:id="${id}" hx-swap-oob="true">
<div tl:replace="toast(${type}, ${title})"></div>
</div>
{"id": "flash", "type": "error", "title": "Saved"}
<div hx-swap-oob="true" id="flash"><div class="toast error"><strong>Saved</strong></div></div>
In a handler, list the wrapper beside the main fragment, for example
renderOobFragments(request, 'todos', ['todo-list', 'toastStack'], context) with
the Shelf helper; in a page, tl:replace="toast('error', ${msg})" renders the same
toast in place.
A fragment name with arguments throws, naming the bare name to pass instead:
<div tl:fragment="toast(type, title)"><strong tl:text="${title}">Title</strong></div>
is addressed with arguments; pass the bare name "toast" instead
An empty () is read as the bare name.
The one difference from in-template invocation
Invoked from another template, tl:replace="toast" without arguments leaves the
parameters unpassed, and they stay null – the context is not consulted. Only
renderFragment reads them from the context:
<div tl:fragment="toast(type, title)" class="toast" tl:classappend="${type}">
<strong tl:text="${title}">Title</strong>
</div>
<div tl:replace="~{ui/toast.html :: toast}"></div>
<div tl:replace="~{ui/toast.html :: toast('warning', 'Careful')}"></div>
{"type": "error", "title": "Saved"}
<div class="toast"><strong></strong></div>
<div class="toast warning"><strong>Careful</strong></div>
Both forms of the in-template call are valid; pass arguments when you want values.
Two caveats:
- Two fragments sharing a name is an authoring error with no engine rule: a top-level render takes the first in document order, an in-template call the last.
renderFragmentsrenders several fragments against one context, so two fragments that both declaretitleread the sametitle.
Directives on the tl:fragment element itself act as they would in place when
the fragment is rendered as a response: a tl:each renders one element per item,
a removed root (tl:if false, tl:unless true, tl:remove="all") renders
nothing and renderFragments concatenates the others, and a tl:replace renders
its target.