aicoded.dev

Expressions: the {{ }} language

Expressions are compiled to Go, not interpreted: what you write between the braces becomes a Go expression in the page's generated code, so the Go compiler checks its names and types. Each value is escaped for the place in the page where it lands.

Where expressions go

<p>Total: {{ price * quantity }}</p>              <!-- element text -->
<span class="badge {{ tone }}">…</span>           <!-- a quoted attribute value -->
<a href="/users/{{ u.Login }}">…</a>              <!-- part of a URL -->
<div ssr:if="user.Age >= 18">…</div>              <!-- a condition, without braces -->
<li ssr:for="i, lang in langs">…</li>             <!-- a loop, without braces -->
<ssr:json name="langs-data" value="langs"/>       <!-- a value for scripts, without braces -->

An attribute value may mix fixed text with any number of expressions. Attribute values with an expression must be in quotes (E-GEN-024).

Escaping

{{ expr }} picks its escaper from where it stands, when the page is generated:

Where Example What is written
element text, also in <title> and <textarea> <p>{{ note }}</p> the text with &, <, >, " and ' as character references
a quoted attribute value class="{{ tone }}" the same
a whole URL attribute href="{{ link }}" the URL, percent-encoded where needed; a URL whose scheme is not http, https or mailto becomes about:invalid#aicoded-unsafe-url
a URL after fixed text with a path or scheme href="/notes/{{ id }}" the value percent-encoded, keeping /, ? and the other URL characters
a URL right after its leading / href="/{{ slug }}" the same, but a leading / is encoded and an empty value is ., so the URL never starts with //
a URL after ? or # href="/find?q={{ q }}" the value percent-encoded as one query part, & and = included

URL attributes are href, src, action, formaction, poster, cite and the like, and every attribute whose name contains src, uri or url. Inline scripts, styles, event handlers and attributes that load code take no expressions at all; see template syntax.

{{$ expr }} writes markup as it is. It takes only a web.SafeHTML, and only in element text: never in an attribute, <title> or <textarea> (E-GEN-029). A web.SafeHTML is made in Go with web.HTMLConst from a string constant, web.EscapeHTML from any text, or web.JoinHTML from other web.SafeHTML values, so a viewer's text can only reach it escaped:

data.Intro = web.JoinHTML(web.HTMLConst("You are signed in as <strong>"),
	web.EscapeHTML(auth.Viewer(ctx).Name), web.HTMLConst("</strong>."))
<ssr:var name="intro" type="web.SafeHTML"/>
<p>{{$ intro }}</p>

Literals and operators

Kind Examples
strings 'text', "text", `text`; single quotes read best inside attributes
numbers 42, -7, 3.14
names variables, loop variables, Go's true, false and nil
Operators
arithmetic + - * / %
comparison == != < <= > >=
logic && `
grouping ( … )
fields and methods user.Name, user.FullName()
indexing users[0], scores['alice']
calls formatMoney(balance, 2), len(users)
conditional cond ? whenTrue : whenFalse

Go's rules apply: no conversion between number types, no truthiness, and + on strings joins them. The binary operators are written into Go as they are, so Go's precedence holds: {{ 1 + 2 * 3 }} is 7.

The conditional operator

cond ? a : b compiles to render.If(cond, a, b), a function call:

The usual nesting for a field's state reads well because it nests in the middle:

class="{{ form.IsValidated() ? input.HasError() ? 'invalid' : 'valid' : '' }}"

Names you can use

There are no imports in templates. To use another package, wrap it in a function next to the template, or pass the result in a variable.

An expression is app code: aicoded check holds the Go code written from it to the same rules as the Go code next to the template, such as constant SQL (E-LINT-007) and no personal data or secret in a log or span (E-LINT-008), and points to the template's line.

Some names are the generated code's own and refused (E-GEN-042): w, s, render, web, form (outside a form), reactive, io, context, http, json, strings, sync, errors, slog, and names starting with _html; and the names the page's generated files declare: routeKey, route, state, NewRoute, RouteData, RouteDataProvider, ReactiveState, NewHandler, assets, assetsDir, names starting with renderBlock_, and a form's Form<Name>Values.

How values are written

In forms

Inside <ssr:form>, form is the form's values, and input (in <ssr:input> and <ssr:select>) or textarea (in <ssr:textarea>) is the field being written:

<ssr:input name="login" type="text" required
           class="{{ form.IsValidated() ? input.HasError() ? 'invalid' : 'valid' : '' }}"/>
<p class="error" ssr:if="form.Login.HasError()">{{ form.Login.GetError() }}</p>

See forms.

Live expressions

An expression that reads a variable declared with reactive="true" becomes a live part of the page, which the server renders again and sends when the value changes. See live values.

See also

Markdown · Source on GitHub · framework f46741f