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.
tl:attr – set any attributes
tl:attr sets one or more attributes from a comma-separated list of
name=${value} pairs:
<div tl:attr="data-id=${item.id},title=${item.name}">content</div>
Set multiple attributes with one
tl:attr. HTML forbids duplicate attribute names, so the HTML5 parser keeps only the firsttl:attron an element and silently drops the rest – before Trellis runs. Always combine them into a single comma-separatedtl:attr.TemplateValidatorwarns when a duplicate is detected.
A null value removes the attribute. Boolean HTML attributes (disabled,
checked, and so on) render valueless when true and are removed when false.
Shorthand attributes
These shorthands set a single named attribute directly, and read more naturally than the generic form:
<a tl:href="${url}">link</a>
<img tl:src="${imageUrl}">
<input tl:value="${val}">
<div tl:class="${className}">styled</div>
<div tl:id="${elementId}">identified</div>
tl:hrefsetshref– pairs naturally with a URL expression@{...}.tl:srcsetssrc.tl:valuesetsvalue.tl:classsetsclass– it replaces the existing class, it does not append.tl:idsetsid.
tl:classappend / tl:styleappend – append
Where tl:class replaces, these two append to an existing class or style
attribute, leaving what is already there in place:
<div class="card" tl:classappend="${active} ? 'active' : ''">content</div>
<div style="color:red" tl:styleappend="font-weight:bold">content</div>
The first renders class="card active" when active is truthy.
A blank existing class or style (empty or whitespace only) counts as absent, so
<div class="" tl:classappend="'a'"> renders class="a", not class=" a".
tl:attrs – spread a map of attributes
tl:attrs takes a single expression that evaluates to a Map and writes each
entry as an attribute. It is how a component places
the attributes it receives through a ...rest parameter.
<a href="/a" class="btn" style="color:red" tl:attrs="${attrs}" tl:href="@{/z}">go</a>
{"attrs": {"href": "/m", "class": "wide", "style": "top:0", "data-n": 1}}
<a href="/z" class="btn wide" style="color:red; top:0" data-n="1">go</a>
The merge rules:
- Spread runs first in the attribute group, so the element's own
tl:attr, shorthands,tl:classappendandtl:styleappendoverride spread entries. Above,tl:hrefbeat the map'shref. - Against literal attributes an entry overwrites, except
classandstyle, which append.tl:classremains the explicit full replace. - Values behave as in
tl:attr:nullremoves the attribute,truerenders a boolean attribute valueless andfalseremoves it. - A
nullmap is a no-op.
<input title="old" tl:attrs="${attrs}">
{"attrs": {"title": null, "disabled": true, "required": false, "value": "v"}}
<input disabled="" value="v">
Attribute names come from the map at runtime, which no other directive does,
so they are validated. Any name HTML allows passes (@click, :class, _),
but an empty name, or one with whitespace, a control character, ", ', >,
/, = or a Unicode noncharacter throws. A non-Map value throws, and a key
starting with the configured attribute prefix (tl: by default, compared
case-insensitively) throws, so a spread map can carry data but
never a directive:
<div tl:attrs="${attrs}"></div>
{"attrs": {"tl:remove": "all"}}
starts with the directive prefix
<div tl:attrs="${attrs}"></div>
{"attrs": "class=x"}
tl:attrs expects a Map but got String
<div tl:attrs="${attrs}"></div>
{"attrs": {"bad name": "x"}}
illegal attribute name "bad name"
A key that differs from an existing attribute only in case replaces it, so
an element never carries two spellings of one name. Only the exact key class
(or style) appends; write keys lowercase:
<p class="a" tl:attrs="${attrs}"></p>
{"attrs": {"Class": "b"}}
<p Class="b"></p>
An element carries at most one tl:attrs (the HTML5 parser drops duplicates, as
with tl:attr).
Trust the map
Entries are written as given: values are only HTML-escaped, never checked for meaning, and keys are only checked for syntax. Keep the map out of reach of untrusted input:
- Never let untrusted data choose keys. A key picks which attribute is set, so it decides what the element does.
- Validate values under
href,src,srcdoc,on*andstyleexactly as you would fortl:attr. Ajavascript:URL, asrcdocdocument or an event handler passes through verbatim. - A
nullvalue removes the attribute, even a literal one on the element. A map can dropsandboxfrom an iframe oractionfrom a form.
<iframe sandbox src="/ok" tl:attrs="${attrs}"></iframe>
<a href="/safe" tl:attrs="${link}">go</a>
{"attrs": {"sandbox": null, "srcdoc": "<p>hi</p>"}, "link": {"href": "javascript:alert(1)"}}
<iframe src="/ok" srcdoc="<p>hi</p>"></iframe>
<a href="javascript:alert(1)">go</a>