Strings
A function that returns HTML is a first-class way to write markup here.
Every place Streamlord takes HTML takes a String, and the Html that
interpolate returns as well. A function returning a triple-quoted literal
is not a fallback for people who have not learned the DSL. It is one of the three supported
ways, and the editor tooling treats it as such.
@org.intellij.lang.annotations.Language("HTML")
fun counter(count: Int): String =
$$"""
<div id="counter" data-signals="{count: $$count}">
<button data-on:click="$count++">Raise</button>
<span data-text="$count"></span>
</div>
""".trimIndent()
get("/counter") {
call.respondDatastar { patchElements(counter(3)) }
}
Two things make this comfortable.
$$"""..."""
Kotlin 2.2 and newer. In a multi-dollar string a single $ is just a dollar, so $count reaches
the browser as the signal it is, and $$count is the Kotlin template.
Without it you are back in the $ trap: $count either fails to compile or,
when a count happens to be in scope, silently ships its value, data-text="3", or
data-text="" when it was empty. On older Kotlin, write ${'$'}count.
@Language("HTML")
From org., which your build already has through the Kotlin standard
library. Streamlord declares it compileOnly, so nothing new reaches you.
IntelliJ then treats the string as HTML: highlighting, tag completion, and, with the official
Datastar plugin, completion of every data-* attribute. Streamlord’s own parameters already
carry the annotation (patchElements, PatchElements, respondElements, datastarElements,
ElementsResponse; JSON for signals, JavaScript for scripts), so a literal passed straight in
is injected without you writing anything. On your own functions, add it yourself.
The VS Code extension does not need the annotation: it treats a string as HTML when it opens with
a tag, carries the annotation, by its short name or its qualified one, or has a // language=HTML
comment, and gives it the same diagnostics, completions, hover and highlighting as a template file.
A string handed straight to a parameter of a function of the same file that carries the annotation
gets all of it but the highlighting. Both editors judge the values written into such a string.
The guard
The DSL guards its own expressions because it builds them. A string arrives finished, so the guard has to walk it, and that is opt-in:
install(StreamlordPlugin) { guardElements = true }
With it on, every element patch and elements response leaving that instance is walked by
ElementsGuard. It finds each data-* attribute whose value is an expression and runs it through
ExpressionGuard, so a data-text="" left behind by a template that ate an empty value throws
InterpolatedExpressionException naming the attribute instead of reaching the browser.
The same walk catches a mistyped attribute. data-onn:click is one letter from data-on:click
and throws MistypedAttributeException saying so. A name that carries a key or a modifier is
judged on any one-letter slip, because data-signal:name is nobody’s own attribute. A bare
data-* name is judged far more narrowly: only a changed letter in a long name, so
data-indicater and data-computer are caught while data-test, data-kind, data-size and
data-theme are yours and pass untouched. A bare name that merely adds a letter passes too:
data-signal is left alone, because data-animated and data-effects are honest words in the
same shape.
The guard takes two letters swapped for one slip as well, where a key or a modifier follows:
data-no:click. The editors warn about the names the guard throws for, and go one step further
with a hint, where a bare name one edit away shows that Datastar was meant: its value reads a
signal or calls an action where an expression could start, data-shwo="$open", or it stands
without a value as the attribute it is near is written, data-persits. data-test="login" says
nothing there, and neither does data-test="costs $5" or a value with a template of its own.
With the guard on, a patch without a selector, which the client matches to the page by id, needs
an id on each of its top-level elements: patchElements( throws
DatastarEventValidationException saying <p> has no id, since the client would skip it with
only a console warning. Without the guard such a patch is sent as written, because the SDK
specification’s own tests send <div>Merge</div> that way.
It is a small scan that builds no tree and copies no markup, and it skips <script> and <style>
bodies. ElementsGuard. is also there to call directly, which is worth doing in the
tests of your markup functions.
In IntelliJ, where nothing flags an unknown data-* name on its own, this guard is the check.
Values from outside
guardElements walks a finished string, so it can tell you an expression was eaten. What it cannot
tell you is where a value came from, because by then Kotlin has concatenated everything.
interpolate turns that around: mark each value where it stands, and Streamlord keeps it out of
the string until the markup is whole, which means it knows exactly where each value landed.
fun hit(title: String, url: String): Html =
interpolate { """<li><a class="lt-link" href="${+url}">${+title}</a></li>""" }
The + marks a value. It may stand in a loop, rows., and
a trim call on the string runs before the values go in. A value written without the mark is filled
in by Kotlin as in any string, neither escaped nor refused: that is right for a constant and for
markup you built, and the editors warn of anything else and offer to mark it. A number is never
marked, since + on a number is Kotlin’s own, and is written as the number it is. A mark belongs
to the block it is written in, and written anywhere else it is no mark and no value stands there:
do nothing to the string but trim it. Inside the block this is the block. So is the receiver of a call written without one, toString() or an extension of your
own on Any, and a unaryPlus of your own on String is not reached there, since the block’s +
comes first. The editors know the block by the name interpolate, and not by another name you
import it under.
A mark you forget is caught by the editors alone: the code compiles, and the value is written as it is. Where nobody has an editor open, the analysis holds the project to it in one test:
@Test
fun `no value reaches a page without its mark`() {
val failures = Analyzer().analyzeProject(java.io.File("src/main/kotlin")).failures(strict = true)
assertTrue(failures.isEmpty(), failures.joinToString("\n") { it.format() })
}
The same rule with the values as arguments, which is the form Java has:
fun hitByPlace(title: String, url: String): Html =
interpolate("""<li><a class="lt-link" href="%s">%s</a></li>""", url, title)
%s is a placeholder and %% writes one %. Every other % is literal, so width: 50% and
/a%20b need no ceremony. A miscounted placeholder throws rather than shipping a half-filled page.
In a block a % is always literal.
What happens to a value is decided by where it landed, not by where it came from, and it is the
same for a value marked with + and for the value of a %s:
| Where the value lands | What happens to it |
|---|---|
| Element text | Escaped |
| A quoted attribute that is not Datastar’s | Escaped |
A URL attribute: href, src, action, formaction, xlink:href, poster, cite, background, ping, manifest, and values, to or from on an SVG animation | Escaped, and refused unless the whole URL, every value in it written, is relative, http, https, mailto or tel |
A URL the browser loads code from: src of <script>, <iframe> or <embed>, href of <base> or <link>, data of <object>, href of an SVG <script> | Escaped, and refused unless the markup before the value already fixes the host: /x, #, ?, or a whole origin such as https://cdn. |
The content of a <meta> that starts with a time, as http-equiv="refresh" reads it | Escaped, and the URL after url= refused unless it is relative, http, https, mailto or tel |
A style attribute | Refused, unless it is a number |
A data-* attribute Datastar evaluates, an expression or a signal filter, or follows as a signal path: data-bind, data-ref, data-indicator; and Pro’s data-match-media, whose query the reference writes as a string literal | Refused, unless it is a number or a boolean |
A data-* attribute Datastar reads as it stands: data-nonce, data-preserve-attr, data-ignore, data-ignore-morph | Escaped |
An event handler such as onclick, or srcdoc | Refused |
| A tag name, an attribute name, an unquoted value | Refused |
Inside <script> or <style> | Refused |
So the url in the example above may be /heads/1 or https://thurn., and a javascript:
URL throws instead of becoming a link that runs. The value is judged whole, as the browser reads it:
a value that ends a path the markup begins takes anything, because the markup already chose
where it points, and href="${+a}${+b}" cannot be made into javascript: across its two values.
Character references are decoded once the attribute is whole, as the browser does, so
href="&${+a}" cannot be finished into javascript: by its value. A Trusted value counts
toward the URL as the markup does: it is written as it stands, and the URL is still judged whole,
so href="${+a}${+b}" given Trusted( and javascript:alert( throws. Only a URL with no other value in it goes
unjudged.
A URL that loads code asks more of the markup. https:// settles the scheme of a <script src>
but not whose script it is, so a value there is refused until the markup has written the host
too: <script src="https://cdn. takes a file name, <script src="${+file}">
takes nothing. A single / is not enough on its own either, since the value could add a second
and name another host; /js/ is. The same goes for <link href>, whatever its rel, since a stylesheet or a
module loads from there too. The exception says so, and its loadsCode tells such a refusal apart.
Wrap a URL you chose yourself in Trusted.
The markup is read the way the browser’s tokenizer reads it, comments, end tags and all, and in more
than one way: as HTML, as the inside of an <svg> or <math>, where a title or a textarea
holds elements rather than text, and following the browser’s own stack of open elements, which
switches between HTML and svg or math, and the rules for CDATA sections, as the markup opens and
closes them. A value has to be safe every way, since a patch with an SVG namespace carries no
<svg> of its own. A <noscript> holds elements, as the client parses a patch with scripting off;
markup that mentions one is also read with scripting on, as a page loads it, where a noscript holds
text, and the stricter reading wins. So a title or a textarea that shows markup as a code sample
cannot take a value inside a data-* attribute of that sample; make the whole sample one value
instead, where it is text either way.
One thing the reading does not follow yet is the browser building the page: inside a <select> the
browser drops start tags such as <title> or <style> that the reading still takes as the start of
text, so markup that writes one there can put a later value somewhere it is not judged. Only
markup you write yourself can do this, never a value; leave such tags out of a <select>.
The refusals are the point. Escaping cannot save these: a value in a data-* attribute Datastar
evaluates becomes part of a Datastar expression, and your own server signed the page it arrived
on; a value in data-bind, data-ref or data-indicator is a signal path the client follows
without a guard, so __proto__. there writes into every object of the page; a value in an
attribute name or an unquoted value can add attributes beside itself, because escaping does not
escape a space; HTML escaping inside a <script> is meaningless; and an escaped value in
onclick or at the head of an href is still something the browser runs. UnsafeInterpolationException
says which value, where it landed, and what to do instead.
val name = "Gorvek"
val heads = 3
interpolate { """<li data-text="${+name}"></li>""" } // throws
// Passes: a number carries no expression, and needs no mark.
interpolate { """<li data-signals="{n: $heads}"></li>""" }
A number or a boolean is let into a Datastar attribute because its text is digits, a dot, a sign
or true/false. A number here is a kotlin.: a UInt or a ULong is not one, so it is
refused there; write n.. No string renders that way and also closes a quote, so the common honest case
of a server-rendered initial signal needs no waiver.
Markup built from markup
What interpolate returns is Html: markup whose values have been through it. Hand it to
patchElements, respondElements or datastarElements as it is; inside respondDatastar { }
patchElements( needs no import of its own. Hand it to another interpolate, and it is
written as it stands in element text, as long as its own markup closes everything it opens and
ends nothing it did not open. An Html that ends inside a tag, a quoted value, a comment or a
<script>, leaves an element open, interpolate( or an <li> without its </li>, or
ends one it did not open, x</div>, would change how the browser reads the values after it, so it
is escaped like a string instead. Anywhere else, inside
an attribute, it is characters like any value, and escaped or refused as one.
val heading = interpolate { """<h2 class="lt-heading">${+"Gorvek"}</h2>""" }
interpolate { """<section id="hero">${+heading}<p>${+"<the oath>"}</p></section>""" }
A list of rows is a list of Html, and joinToHtml() makes them one, to be marked as a single value.
Each row already closes what it opens, so nothing is read again or escaped:
val hits = repository.search("gate")
val rows = hits.map { interpolate { """<li><a href="${+it.url}">${+it.title}</a></li>""" } }
interpolate { """<ul class="lt-list">${+rows.joinToHtml()}</ul>""" }
joinToString would give a String, which interpolate escapes, so the rows would show as their
tags. Where you build the events yourself, as a Flow does on
Spring WebFlux, PatchElements( and ElementsResponse( take the
Html too.
Only interpolate makes an Html, and joinToHtml() from the ones it made, so holding one says
where it came from. A Kotlin template
writes its markup, so "<main>$page</main>" works too, but the editors cannot see that
page is markup unless its type says so. An Html is never equal to a String: JUnit’s
assertEquals(, or AssertJ’s isEqualTo, compiles and fails though
both print the same, so compare .text.
When you mean it to be markup
Wrap it in Trusted, which writes the value as it stands wherever it lands:
val hits = repository.search("gate")
interpolate { """<ul class="lt-list">${+Trusted(renderResults(hits))}</ul>""" }
That waives both the escaping and the refusals for that value, which is right for a fragment you rendered yourself and wrong for anything that came out of a request. It is a word in your source that a reviewer can search for, which is the whole reason it is a type and not a flag. It vouches for itself alone: in a URL with other values it is part of the URL, and the URL is judged whole. Its text is markup like the literal around it, so the other values are judged where it puts them:
val name = "Gorvek"
val title = Trusted("title")
val onclick = Trusted("onclick")
val script = Trusted("script")
interpolate { """<button ${+title}="${+name}">""" } // escaped into the title
interpolate { """<button ${+onclick}="${+name}">""" } // throws: the browser runs it
interpolate { "<${+script}>${+name}</${+script}>" } // throws: a script body
This is the editors’ rule, at run time
The editors ask the same question of a Kotlin template in an HTML string as you type, with the
same reading of the markup: core’s, which interpolate uses and the VS Code analysis is held to.
Every $name, ${...} and value joined with + is judged by where it lands, in a + chain handed
straight to a DSL call too:
| Where the value lands | What the editors say |
|---|---|
Element text, a quoted attribute, a URL whose literal start settles the scheme (#, /, ?, https://) | unescaped-interpolation: a hint, a warning when the value is a String, or markup anywhere but element text, where markup says nothing; with a fix that marks the values with + in interpolate { }, and in element text a second, “Mark … as markup”, that wraps the value in Trusted( |
The start of a URL, style, a data-* expression, signal path or filter, <script>, <style>, on*, srcdoc | unsafe-interpolation: a warning, since escaping cannot help there, but none for a number, a boolean or null in code, nor for a boolean in style; at the start of a URL, the URL of a <meta> refresh among them, with the fix that marks the values with + in interpolate { }, which refuses a URL that runs, and none after a scheme the markup writes that does more than navigate, javascript: or data:, since interpolate refuses every value there; in the body of a <style> with the fix that marks the value as Trusted( |
A URL the browser loads code from (src of a script, an iframe or an embed, href of a base or a link, data of an object) whose literal start does not fix the host | unsafe-interpolation: a warning, and no fix, since interpolate refuses it too; in a call to interpolate, an error where the value is known |
| An attribute value without quotes | unsafe-interpolation: a warning, a hint for a number or a boolean, with a fix that quotes the value, put first only for a number or a boolean, since any other value is still to be escaped once it is quoted |
| A tag name, an attribute name, a list of attributes, an end tag | unsafe-interpolation: a hint, a warning when the value is a String or markup; an end tag takes no attributes, so write it from literals alone |
$name where a Datastar signal could stand | kotlin-interpolation, the dollar trap; a hint when name is declared a number or a boolean, which is safe to write in, so only what you meant is in question |
A value the editor can see is yours says nothing anywhere: a const val, also a qualified one such
as ${Routes., a literal, ${"$"}, an enum entry such as ${Tab., an if or a when
whose every branch is one, and a call to one of Streamlord’s expression helpers whose arguments are
all yours or a declared number or boolean, ${signal( or ${post(. A helper is
only as safe as what it is given: ${signal( writes the request’s text into a Datastar
expression, where it runs, so it is judged as the String it returns. IntelliJ reads the enum
itself and takes an entry only when the enum does not override toString. Any other value is judged by what interpolate would let in
where it lands. A number or a boolean says nothing in text, an attribute, a URL, a data-*
expression or style, nor in a <script>, a <style> or an event handler, which digits, true and
false cannot end, though a kotlin., which any class may be, is no digits there; one that may
be null, an Int?, only where escaping is enough and in code, which null cannot end either. Where interpolate would refuse such a value, the rewrite leaves it
unmarked. An unsigned number, a UInt or a 3u, says nothing where escaping is enough and is a hint
in a data-* expression or style: Kotlin writes its digits, but interpolate would refuse it
there. A value that is markup you built, as a whole, says nothing in element text and is a warning
anywhere else, where its quotes and tags can end what holds it: an HTML literal, an
interpolate( or Trusted( call, a value declared Html or @Language(,
kotlinx.html output, or a joinToString whose every element is markup. Html and Trusted are
Streamlord’s own; a com. is judged as any type the editor does not know. Markup joined
to a value is read as one string: in ${"<b>" + query + "</b>"} the literals are markup and
query is the value that is judged. An if, a when or an ?: is judged by its weakest result,
so ${if ( is the String it may be.
VS Code knows what the file it is in declares, each name in the scope it is declared in, and every
const val in the workspace that the file does not declare as something else; it reads a comparison
as a Boolean, arithmetic of numbers it knows as a number, and the name of an entry of an enum the
file shows as yours; IntelliJ also knows
the types, and what it knows of a value comes before anything the text suggests. Nothing here is an error, because a value the text cannot see into may well
be a number.
For a String in element text the editors cannot tell which you hold, so they offer both the
rewrite and “Mark … as markup”, which wraps the value in Trusted(. The rewrite stands first
in the list, and in VS Code neither is the preferred fix, the one Auto Fix applies unasked: text from
outside wants the rewrite, a fragment you rendered yourself wants Trusted, or better, to be
declared Html.
The rewrite, before and after
“Mark the values with + in interpolate { }” is offered on a value’s warning wherever interpolate
accepts every value of the string, and as a context action anywhere else in such a string: among
the intentions in IntelliJ, under Refactor in VS Code. This is what it writes.
The string stays as you wrote it, in the block, with each value marked where it stands. A trim call
stays on the string, and CSS in the body of a <style> is marked as Trusted(, your word that
it is yours. That fix is on the value in the <style>, and the other values say that the fix
marks it so:
class LayoutContext(val pageId: String, val sectionId: String)
fun pageHtmlBefore(k: LayoutContext, pageStyle: String?, mainHtml: String): String =
"""
<div id="${k.pageId}">
<style>${pageStyle.orEmpty()}</style>
<div id="${k.sectionId}">$mainHtml</div>
</div>
""".trimIndent()
fun pageHtmlAfter(k: LayoutContext, pageStyle: String?, mainHtml: String): String =
interpolate { """
<div id="${+k.pageId}">
<style>${+Trusted(pageStyle.orEmpty())}</style>
<div id="${+k.sectionId}">${+mainHtml}</div>
</div>
""".trimIndent() }.text
Under .trimIndent() the fix is first in the list but in VS Code never the preferred one, because
the trim now runs before the values go in: a value that holds a line break no longer changes how much is
trimmed. .trimMargin() has no such catch. Nor is it preferred beside a value that may be null, a
String? or an Int?: a template writes null for it, which no page means, and interpolate
nothing, as the message says.
A $$"..." literal keeps its prefix, so a single dollar that was text for the browser stays text.
Literals joined to values with + become one string, and where they are written differently each
keeps its form, with the value marked at the end of the one before it:
fun priceBefore(name: String) = $$"""<p title="$${name}" data-text="$price"></p>"""
fun priceAfter(name: String) = interpolate { $$"""<p title="$${+name}" data-text="$price"></p>""" }.text
fun rowBefore(name: String, note: String) = "<li title=\"" + name + "\">" + note + "</li>"
fun rowAfter(name: String, note: String) = interpolate { "<li title=\"${+name}\">${+note}</li>" }.text
fun mixedBefore(name: String, note: String) = "<li title=\"" + name + """">""" + note + "</li>"
fun mixedAfter(name: String, note: String) = interpolate { "<li title=\"${+name}" + """">${+note}""" + "</li>" }.text
Every value is marked as it is written, a collection too. interpolate writes a List it is
given as one value, the way a template does, so the page stays as it was:
class Hero(val tags: List<String>)
fun tagsBefore(hero: Hero) = "<p>${hero.tags}</p>"
fun tagsAfter(hero: Hero) = interpolate { "<p>${+hero.tags}</p>" }.text
A value that is yours, a constant, an enum entry or ${"$"}, stays unmarked where interpolate
would refuse it or might escape markup it holds: Kotlin fills it in as before, and interpolate
reads it as part of the markup:
const val SAVE_ROUTE = "/save"
fun saveBefore(label: String) = "<button data-on:click=\"@post('$SAVE_ROUTE')\">$label</button>"
fun saveAfter(label: String) = interpolate { "<button data-on:click=\"@post('$SAVE_ROUTE')\">${+label}</button>" }.text
When no rewrite is offered, the warning of each value ends with the reason:
| What stands in the way | What to do |
|---|---|
A value where interpolate refuses a String: a data-* expression, style, a <script>, an event handler, the markup’s structure | Move that value out first: into an attribute of its own read with el., a class, or a literal. A Trusted there is accepted as it is. |
A call or an if in element text that may give markup, ${if ( | Build that part with interpolate or declare it Html, so that the rewrite does not escape it. |
A call or an index after one literal of a + chain, "<p>" + name + "</p>".uppercase() | The call is that literal’s alone. Put the chain in brackets, or the call on the result. |
| A trim call with a margin that is not a literal | Trim the string yourself, or use ` |
A value that says this, or calls toString(), hashCode(), let { } and their like without a receiver | In the block these are the block’s: name the value first, val self = this, or write the receiver, this@Row.. |
A string in an annotation’s argument or a const val gets no rewrite, since Kotlin takes a
constant there, and neither does a string whose values need no escaping: numbers, constants, an
Html in element text.
A call to interpolate is judged as it will run. A miscounted %s is an error,
interpolate-placeholders, because it always throws. A %s whose value interpolate will refuse,
a String in a data-* expression, is an error where the value is known to be one and a warning
where it is not; a UInt there is an error, with a toLong() fix. And a Kotlin template written
into the format, interpolate(, is interpolate-template: Kotlin fills it in before
interpolate sees the markup, so it is neither escaped nor refused, and the fix turns it into a
%s placeholder with the value among the arguments, or in a block marks it with + where it
stands. In VS Code the fix is not the preferred one under .trimIndent(),
where the trim then runs before the value goes in, nor for a value that may be null, which a
template writes as null and interpolate as nothing. Markup is no exception, an Html or a
Trusted: in interpolate( Kotlin writes the text of inner into the format,
where interpolate reads it again as markup of yours, so a %s in it, which a value may have put
there, becomes a placeholder and the call throws, and a %% becomes %. It is
interpolate-template too, a warning, with the fix that gives it a placeholder of its own, where
interpolate writes it as it is; in a <textarea> or a <title> it escapes an Html, as it does
anywhere but element text:
val inner = interpolate { "<b>${+"Gorvek"}</b>" }
interpolate { """<div class="lt-card">${+inner}</div>""" }
A value marked in element text, or passed for a %s there, that is markup held as a String, h., elements { }, a
joinToString over markup or over a list of Html, or a val set to any of these, is
interpolate-template too, a warning: interpolate escapes it, so its tags are printed as text. Pass the Html itself, or wrap markup you built in Trusted(. A
literal is left alone, "<the oath>" among them: text you chose to have escaped.
At run time the source is gone and only the finished string arrives, so each value has to be marked,
or left a placeholder, for the same question to be asked. That is the whole of what interpolate
wants from you.
On Spring
Spring has no auto-configuration, so the helpers take the bean: datastarElements(,
response., events.. With
Streamlord. the guard is off.
Hand an Html to datastarElements(, not to ResponseEntity.. That compiles, but
Spring writes a body through its message converters, and StringHttpMessageConverter takes a
String only, so no converter writes an Html as markup. Where you need the ResponseEntity
yourself, pass html..