Reference21 min read

Template functions

Every built-in template function — slot, hoist, asset, the URL functions, json, arithmetic, strings and lists — with its signature and an example.

Templates are Go's html/template, so everything it provides is there: if, range, with, define, block, and the standard functions and, or, not, len, index, slice, print, printf, println, eq, ne, lt, le, gt, ge, call, html, js and urlquery. collage adds the functions on this page.

FunctionSignatureReturns
slotslot namethe markup of the fragments in a slot
hoisthoist areathe place hoisted content lands
assetasset patha mounted file's content-addressed URL
stylesheetstylesheet pathnothing; declares a stylesheet for the head
csrfTokencsrfTokenthe hidden input a form's token travels in
pageURLpageURL name [param value]...a route's URL in this render's locale
pageURLInpageURLIn locale name [param value]...a route's URL in exactly that locale
localeURLlocaleURL localethis page's URL in another locale
actionURLactionURL name [param value]...an action's URL in this render's locale
fragmentURLfragmentURL page fragment [param value]...a fragment path's URL in this render's locale
fragmentURLInfragmentURLIn locale page fragment [param value]...a fragment path's URL in exactly that locale
withQuerywithQuery name value [name value]...this page's URL with query parameters set or removed
safeHTMLsafeHTML stringthe string, trusted as HTML
safeURLsafeURL stringthe string, trusted as a URL
dictdict key value [key value]...a map built from pairs
defaultdefault fallback valuevalue, or fallback when it is empty
upperupper stringthe string in upper case
lowerlower stringthe string in lower case
titletitle stringeach word capitalised
joinjoin sep itemsthe items joined by sep
formatTimeformatTime time layoutthe time, formatted
pathEscapepathEscape stringthe string, escaped for one path segment
jsonjson value [spaces] [pretty]the value as JSON
prepre value [spaces] [pretty]the value in an escaped <pre> block
add, sub, mul, div, mod, min, maxadd a binteger arithmetic
addf, subf, mulf, divfaddf a bthe same for float64
trim, replace, contains, hasPrefix, hasSuffix, splitreplace old new stringthe strings functions, the string last
truncatetruncate n stringthe first n characters, with … when anything was cut
first, lastfirst lista list's first or last element
seqseq n1 to n, to range over
keys, hasKeykeys map, hasKey map keya map's keys, sorted; whether it holds one
digdig value key...the value at a path through maps and structs, or nothing

Every function is typed, so the template checker — at registration and in collage check — reports {{add .Title 1}} with a string Title before any request does. Registration also runs html/template's escaper over every fragment's template: one it cannot escape — a <script> string that never closes, {{if}} branches that leave an attribute in different states — is an error naming the page and the fragment, rather than a fragment that fails on its first request.

A function that returns an error fails the template, and the fragment fails with it — under the fragment's own failure policy:

  • a required fragment fails the page;
  • an optional one renders its fallback;
  • or nothing when it has none.

In development mode "nothing" is an HTML comment naming the fragment and its error, and the development panel on top of the page names every failed fragment, fallback or not. In every mode the failure is also logged as a warning. See Fragments and slots.

Bound per render

The first twelve functions need the render they are part of — the fragment, the request, the locale, the application's routes and mounts. Each reads something different:

FunctionWhat it reads
slotthis fragment, and the fragments bound into its slots
hoistthe render's areas, filled once the whole page has rendered
assetthe application's mounts
stylesheetthe head this render declares into
csrfTokena placeholder each reader's token replaces as the response is written
pageURL, actionURL, fragmentURLthe render's locale, with the application's routes
pageURLIn, fragmentURLInthe application's routes; the locale is an argument
localeURLthe page being rendered and its path parameters
withQuerythe page being rendered, its path parameters and the request's query

They are registered when templates are parsed as placeholders, so that a template may call them, and the render engine binds the real implementation on every render. A placeholder that somehow runs outside a render returns an error rather than guessing.

One consequence: an entry under one of these names in Config.Template.Funcs is parsed but never called, and New logs a warning naming it. The other thirty-six can be replaced from Config.Template.Funcs. A plugin can replace none of the forty-eight: see Adding your own.

Where a template's functions come from. collage.New parses the templates with one function map: collage's forty-eight built-ins, twelve of them placeholders, then the functions plugins add with AddTemplateFunc under names of their own, then Config.Template.Funcs, each merged over the one before. On every render, for each fragment, the twelve per-render names are bound again from that render, and so are the functions plugins add with AddRenderFunc. So a Template.Funcs entry named pageURL is parsed and never runs, while one named upper replaces the built-in.collage.New: parse templatesone function map48 built-ins (12 placeholders)plugins: AddTemplateFuncConfig.Template.Funcslaterwinsevery render, each fragment12 per-renderbound from this renderAddRenderFuncplugins', per rendera Template.Funcs entry named…"pageURL"parsed, never runs"upper"replaces the built-in
Every template is parsed in collage.New with one function map: collage's forty-eight built-ins, then what plugins add with AddTemplateFunc under names of their own, then Config.Template.Funcs, each over the one before. Twelve of the built-ins are placeholders. On every render, for each fragment, those twelve are bound again from that render, and so are the functions plugins add with AddRenderFunc. An entry of yours under one of the other thirty-six names, such as upper, replaces the built-in; one under a per-render name, such as pageURL, is parsed and never runs.

slot

{{slot "name"}}

Renders every fragment bound to this fragment's slot name, in binding order, and inserts their markup unescaped. slot always means this fragment's slot, so two fragments can each have a slot called "sidebar" without meeting.

<article>
  {{slot "content"}}
  <aside>{{slot "related"}}</aside>
</article>
  • Calling slot is what declares the slot: the fragment's Go code needs no WithSlot for it, and one the template calls with nothing bound renders nothing.
  • The check faces the other way: a fragment bound into a slot this template never calls fails registration with ErrUnknownSlot, naming the slot and the slots the template does call. Otherwise a typo on either side of the binding would be a section that is silently missing. A slot named by anything but a literal, {{slot .Which}}, turns the check off for that fragment.
  • An empty slot renders nothing — unless WithSlot made it required:
    • A required slot with nothing bound and no resolver is refused when the page is registered, with ErrRequiredSlotUnfilled, so it never reaches a render.
    • A required slot filled by a resolver is checked at render time instead: a resolver that returns no fragments fails the render with ErrRequiredSlotEmpty.
  • A layout's content goes in {{slot "content"}}, the name collage.DefaultContentSlot holds.

The children's data handlers have already started by the time slot runs: they all start together, before the parent renders. See Fragments and slots.

hoist

{{hoist "head"}}

Marks where content hoisted to area lands. Fragments declare that content from anywhere in the tree — usually from a data handler, or with WithTitle for a title fixed when the program starts — and hoist decides where it goes:

<head>
  <meta charset="utf-8">
  {{hoist "head"}}
</head>
rc.HoistTitle(post.Title)
rc.HoistMeta("description", post.Summary)
rc.HoistLink("canonical", canonicalURL)

It writes a marker, not content, because nothing below it has rendered yet. Once the whole tree has rendered, every marker is replaced with what was declared for its area, so a declaration made deep inside the page still reaches the head. An area nothing was declared for is replaced with nothing.

  • An area's name is letters, digits, _ and -. Anything else fails the template: the marker is an HTML comment, and a name such as {{hoist .Area}} fed from a request could otherwise close it.
  • Two declarations under one key keep one. The innermost fragment's wins; at equal depth, the one later in the page — within a slot, the fragment bound later; between slots, the one the template renders later.
  • Only a fragment that rendered declares anything. For a fragment behind a slot the template never calls, its title, its Hoist* calls and the tags of its Cached calls never reach the page. A fragment that fails takes its hoists with it, so an optional fragment's fallback does not render under the failed one's title.

HoistTitle, HoistMeta, HoistProperty, HoistLink, HoistAlternate and HoistStylesheet write to the "head" area; rc.Hoist(area, key, html) writes to any area you name. A plugin that contributes to the head needs this marker: without it, its content has nowhere to go. See Head and SEO.

asset

<link rel="stylesheet" href="{{asset "/static/app.css"}}">
<img src="{{asset "/static/logo.svg"}}" alt="">

Returns the content-addressed URL of a file in a mount: the file's path with a hash of its contents before the extension.

/static/app.css  →  /static/app.41014ebb6c2d9f07.css

A name derived from the bytes can only ever mean those bytes, which is what makes it safe to serve with a one-year, immutable lifetime: a changed file is a changed name, and the old one is simply never requested again.

  • The path is the URL the mount serves the file at, including the mount's prefix.
  • A file that does not exist is an error, not a URL: ErrUnknownAsset. The alternative is a page that renders fine and links a stylesheet that 404s.
  • A path no mount serves, or an application with no mounts, is ErrUnknownAsset too; the message says when no mount's prefix covers the path at all.
  • So is a name the mount would answer with a 404: a dotfile such as /static/.env, or one that is not a valid path within the mount.
  • Each segment of the file name is escaped, so a #, ? or % in it stays part of the path: /static/100%.css links as /static/100%25.<hash>.css.
  • A static export writes exactly the fingerprinted copies that pages asked for, alongside the originals.

From Go, rc.Asset(path) returns the same URL. See Static assets.

stylesheet

{{stylesheet "/static/gallery.css"}}

Declares that this fragment needs a stylesheet, and renders nothing where it is called. The page's head gets one <link rel="stylesheet" href="…"> with the file's asset URL, where the layout calls {{hoist "head"}}.

A fragment can therefore carry its own styles wherever it is used:

{{stylesheet "/static/gallery.css"}}
<div class="gallery">…</div>

The declaration is keyed by the path, so a stylesheet several fragments ask for appears once. It fails on the same terms as asset. From Go it is rc.HoistStylesheet(path).

csrfToken

<form method="post">
  {{csrfToken}}
  <input name="email" type="email">
  <button>Subscribe</button>
</form>

Renders the hidden input a form's request-forgery token travels in:

<input type="hidden" name="_csrf" value="…">

A whole input rather than the bare value, because the bare value has to be placed in a field with exactly the right name, and a form that gets the name wrong is refused with nothing to explain why.

The value written during the render is a placeholder. It is replaced with each reader's own token as the response is written.

That is why a cached page can carry a form: the cached bytes hold the placeholder, and every reader gets their own token.

  • With Security.DisableCSRF set, csrfToken fails the render with ErrCSRFDisabled: a form expecting a token would otherwise be rendered without one.
  • The field is named _csrf unless Security.CSRFFieldName says otherwise, and it is the name the verifier reads either way, so a renamed field needs no change to the template.
  • A static export has no server to put a token in, so a page carrying one is not exported, and the report says why.

See Forms and actions.

pageURL

<a href="{{pageURL "about"}}">About</a>
<a href="{{pageURL "blog-post" "slug" .Slug}}">{{.Title}}</a>
<link rel="alternate" type="application/rss+xml" href="{{pageURL "feed"}}">

Returns the URL of the page or document registered under name, filling its path pattern from param value pairs. Linking by name means a link follows a page when its path changes.

  • In this render's locale. On a Turkish page, pageURL "blog-post" is the Turkish path. A route with no path in the current locale links its default-locale path instead, so a Turkish page linking an English-only page still renders.
  • Strict. An unknown name (ErrUnknownRoute), an odd number of parameter arguments, a missing or empty parameter, or a parameter the pattern has no placeholder for (ErrRouteParams) fails the render. A link that cannot be built is a bug to find in development, not a 404 for a reader.
  • Values are strings, integers or fmt.Stringers, and are escaped.
  • Some values are refused. A value of . or .., which a browser would resolve as a path step, is refused. So is a float, a bool or nil, with ErrRouteParams naming its type, since none has one obvious spelling in a URL:
<a href="{{pageURL "user" "id" .ID}}">{{.Name}}</a>
  • A name registered as both a page and a document is refused rather than guessed.

From Go it is app.URL(name, locale, params). See Links and locales.

pageURLIn

<a href="{{pageURLIn "tr" "about"}}">Hakkımızda</a>
<a href="{{pageURLIn "en" "blog-post" "slug" .Slug}}">Read in English</a>

pageURL in exactly the locale given, with no fallback: a route with no path in that locale is ErrNoPathInLocale, and a locale no URL can reach — neither the default nor in Locale.Supported — is ErrLocaleUnreachable.

localeURL

{{with localeURL "en"}}<a hreflang="en" href="{{.}}">English</a>{{end}}
{{with localeURL "tr"}}<a hreflang="tr" href="{{.}}">Türkçe</a>{{end}}

The page being rendered, in another locale, with the same path parameters — what a language switcher is made of.

  • A page with no path in that locale is the empty string, not an error, so {{with}} skips a language the page has not been translated into.
  • A locale no URL can reach is still an error (ErrLocaleUnreachable): that is a mistake in the template, not a missing translation.
  • It fails in a render that is not a page's: a document's, or an action's at a URL of its own. A fragment served at a URL its page opened for it renders with that page, so there it links the page.
  • For the <link rel="alternate" hreflang> search engines read, declare them from Go with rc.HoistAlternate — see Head and SEO.

actionURL

<form method="post" action="{{actionURL "logout"}}">{{csrfToken}}…</form>
<form method="post" action="{{actionURL "vote" "id" .ID}}">{{csrfToken}}…</form>

The URL of the action registered under name, built as pageURL builds a page's: the path is written once, in Go, and every form posting to it follows it.

  • In this render's locale, falling back to the default one, as pageURL does.
  • As strict as pageURL. An unknown name is ErrUnknownRoute, and parameters that do not fill the pattern are ErrRouteParams.
  • Actions have names of their own.actionURL "login" is the action and pageURL "login" the page, since a login page and a login action are the usual pair. A page's own action is under the name it was registered with: "contact:POST" for WithAction("POST", …) on a page named contact.

From Go it is app.ActionURL(name, locale, params).

fragmentURL

<div data-live="{{fragmentURL "home" "cpu-usage"}}">{{slot "cpu-usage"}}</div>
<div data-live="{{fragmentURL "post" "comments" "slug" .Slug}}">…</div>

The path a page opened for one of its fragments with WithFragmentPath, built from the page's name and the fragment's. The path is written once, in Go, and every link to it follows it.

  • In this render's locale, falling back to the default one, as pageURL does.
  • As strict as pageURL. An unknown page is ErrUnknownRoute, a fragment the page did not open is ErrUnknownFragmentPath, a fragment opened at two paths in one locale is ErrAmbiguousFragmentPath, and parameters that do not fill the pattern are ErrRouteParams. Each fails the render.

From Go it is app.FragmentURL(page, fragment, locale, params). See Links and locales.

fragmentURLIn

<div data-live="{{fragmentURLIn "tr" "home" "cpu-usage"}}">…</div>

fragmentURL in exactly the locale given, with no fallback: a fragment with no path in that locale is ErrNoPathInLocale, and a locale no URL can reach is ErrLocaleUnreachable.

withQuery

<a href="{{withQuery "page" (add .Page 1)}}">Older posts</a>
<a href="{{withQuery "tag" ""}}">Every tag</a>
<a href="{{withQuery "page" 1 "sort" "new"}}">Newest first</a>

The page being rendered, with the request's query and those parameters set. A value of "" removes a parameter, and the others stay as they were. On /blog?tag=go&page=2, the three links above are /blog?page=3&tag=go, /blog?page=2 and /blog?page=1&sort=new&tag=go: the query is written with its names sorted.

  • The path is the page's own URL, in the render's locale with its path parameters, falling back to the default locale as pageURL does. In a fragment refreshed from a URL of its own, the link still leads to the page, not to the bare fragment. In an action at a URL of its own, which has no page, it is the action's URL.
  • The query is the one the render sees. On a cached page that is only the parameters in its cache key, never a reader's other ones, so a link written into the shared copy cannot carry one reader's utm_source to the next.
  • Names are strings, and values are strings, integers or fmt.Stringers, as pageURL's are. Another type, or a name without a value, fails the render.

safeHTML

{{safeHTML .RenderedMarkdown}}

Marks a string as trusted HTML, so html/template inserts it without escaping. It is an escape hatch: use it only for markup you generated or sanitised yourself, never for anything a user typed.

safeURL

<a href="{{safeURL .ExternalLink}}">Visit</a>

Marks a string as a trusted URL, bypassing html/template's URL sanitisation — which otherwise replaces a scheme it does not trust, such as javascript:, with #ZgotmplZ. Only for URLs you have validated.

dict

{{template "card" dict "Title" .Title "URL" (pageURL "post" "slug" .Slug)}}

Builds a map from alternating keys and values, for passing several values into a sub-template. Keys must be strings, and the arguments must come in pairs; either mistake fails the template, with a message that says which.

default

<h2>{{default "Untitled" .Subtitle}}</h2>
<h2>{{.Subtitle | default "Untitled"}}</h2>

Returns value, or fallback when value is the empty string. Both arguments are strings — the fallback comes first so that the piped form reads naturally, since a pipeline passes its value as the last argument.

upper and lower

<span class="badge">{{upper .Status}}</span>
<code>{{lower .Code}}</code>

strings.ToUpper and strings.ToLower.

title

<h1>{{title .Name}}</h1>

Upper-cases the first letter of every word and lower-cases the rest. A word is a run of letters, so anything else — a space, a hyphen, an apostrophe — starts a new one:

InputOutput
hello worldHello World
iPHONE caseIphone Case
o'neil-smithO'Neil-Smith

join

<p>Tags: {{join ", " .Tags}}</p>

strings.Join(items, sep), with the separator first. items must be a []string.

formatTime

<time datetime="{{formatTime .Published "2006-01-02"}}">
  {{formatTime .Published "2 January 2006"}}
</time>

t.Format(layout), with a reference-time layout. t is a time.Time. It is formatted in whatever location it carries; convert it in the data handler if you want another.

pathEscape

<a href="https://example.com/wiki/{{pathEscape .Term}}">{{.Term}}</a>

url.PathEscape: the string escaped to sit in one segment of a path, so a / in it becomes %2F rather than a step down. A link to one of your own pages needs none of this: pageURL escapes its parameters itself.

json

<script type="application/json" id="chart-data">{{json .Series 2 false}}</script>

The value as JSON, indented by two spaces unless told otherwise: {{json v 4}} indents by four, and {{json v 2 false}} writes one line. The spaces are 0 to 16.

It returns template.JS. Inside a <script> — application/json data, or a script that reads it — it is written as it is, and <, > and & stay \u003c-escaped, so a value cannot close the script. Anywhere else it is escaped like any other text. A value encoding/json cannot encode, such as a channel, fails the render.

pre

{{pre .}}

The value in a <pre> block, for looking at what a template was given. A string or a []byte is shown as it is; anything else as json writes it, with the same optional spaces and pretty. The content is always escaped.

Arithmetic

<p>Page {{.Page}} of {{.Pages}}, posts {{add (mul (sub .Page 1) .PerPage) 1}} onwards</p>
<p>{{printf "%.1f" (divf .Rating 2.0)}} / 5</p>

add, sub, mul, div, mod, min and max take two ints, and addf, subf, mulf and divf two float64s. div, mod and divf by zero fail the render.

Strings

<h2>{{.Slug | replace "-" " " | title}}</h2>
{{if hasPrefix "https://" .Link}}<a href="{{.Link}}" rel="external">{{.Link}}</a>{{end}}
<p>{{truncate 140 .Summary}}</p>

trim is strings.TrimSpace. replace old new s, contains sub s, hasPrefix prefix s, hasSuffix suffix s and split sep s are the strings functions with the string last, so each reads in a pipeline. replace replaces every old, and split returns a []string.

truncate n s cuts s to its first n characters and puts … after them when anything was cut. It counts characters, not bytes, so a Turkish letter is never split in half. A negative n fails the render.

Lists and maps

{{with first .Posts}}<a href="{{pageURL "post" "slug" .Slug}}">Latest: {{.Title}}</a>{{end}}
{{range seq 5}}<span class="star">{{.}}</span>{{end}}
{{range keys .Counts}}<li>{{.}}: {{index $.Counts .}}</li>{{end}}
{{if hasKey .Flags "beta"}}<span class="badge">beta</span>{{end}}
  • first list and last list are a slice's or an array's first and last element, and nothing for an empty one, so {{with}} skips it.
  • seq n is 1 to n, for a loop that counts. It is empty when n is below 1, and more than 100000 fails the render.
  • keys map is a string-keyed map's keys, sorted, so a loop over them renders the same way every time. hasKey map "k" says whether the map holds k, even with a zero value under it.
  • Each fails the render when handed something else: a map to first, a list to keys.

dig

{{with dig .Settings "theme" "accent"}}<meta name="theme-color" content="{{.}}">{{end}}

The value at that path through maps with string keys and the exported fields of structs, following pointers. A path that leads nowhere — a missing key, an unexported field, a nil pointer on the way — is nothing rather than an error, so {{with dig …}} handles a value that is optional.

Adding your own

Add functions with Config.Template.Funcs, before New:

app, err := collage.New(&collage.Config{
	Template: collage.TemplateConfig{
		Root: "templates",
		Funcs: template.FuncMap{
			"money": func(cents int64) string {
				return fmt.Sprintf("$%d.%02d", cents/100, cents%100)
			},
		},
	},
})

They are merged over the built-ins, so an entry under a built-in name — other than the per-render ones — replaces it. An entry under a per-render name is accepted and never runs, and New logs a warning naming it.

They must be there before New because html/template can only call a name that was in its function map when the template was parsed; a template calling a name nobody registered fails in New, not at the first request.

A plugin adds functions the same way, from its Configure phase; an application's entry under the same name wins. A plugin cannot take a built-in's name: AddTemplateFunc refuses it with ErrDuplicateTemplateFunc. See Writing a plugin.

A plugin's AddRenderFunc function is bound per render, like the twelve above, but follows the same two rules:

  • An application's entry under its name wins, as over AddTemplateFunc, and New logs it once.
  • Like AddTemplateFunc, it cannot take any of the forty-eight built-in names. AddRenderFunc refuses them with ErrDuplicateTemplateFunc.

Neither may take a name of the template language itself — eq, len, index, print, html, js, urlquery and the rest of Go's builtins and escapers: ErrDuplicateTemplateFunc again.

Anything that needs the request belongs in a data handler rather than a function: that is where the page's data comes from anyway.

Example: a product page in two languages

The shop from Links and locales sells in English and Turkish. Its product page, with a layout around it, calls nine of the twelve per-render functions:

FunctionIn the example
assetthe shop's stylesheet, and the product's picture, whose path comes from the data
hoistwhere the title and product.css land in the head
localeURLthe language switcher
slotthe layout's content, and the product's stock box
stylesheetproduct.css, which only this page needs
pageURLthe link back to the catalogue
fragmentURLthe stock box's own URL, for a script that refreshes it
actionURLthe "add to basket" form's target
csrfTokenthat form's token

The catalog package stands for your own data layer, and keeps each product's name in both languages. The handler picks the labels for the render's locale and hoists the product's name as the title:

type labels struct {
	Back string
	Add  string
}

var labelsIn = map[string]labels{
	"en": {Back: "All products", Add: "Add to basket"},
	"tr": {Back: "Tüm ürünler", Add: "Sepete ekle"},
}

type productView struct {
	catalog.Product // ID, Name, Image
	Labels          labels
}

func loadProduct(ctx context.Context, rc *collage.RenderContext) (productView, []string, error) {
	id := rc.Param("id")
	p, err := catalog.Find(ctx, id, rc.Locale)
	if errors.Is(err, catalog.ErrNoProduct) {
		return productView{}, nil, fmt.Errorf("catalog: no product %q: %w", id, collage.ErrNotFound)
	}
	if err != nil {
		return productView{}, nil, err
	}
	rc.HoistTitle(p.Name)
	return productView{Product: p, Labels: labelsIn[rc.Locale]}, []string{"product:" + id}, nil
}

func loadStock(ctx context.Context, rc *collage.RenderContext) (int, error) {
	return catalog.Stock(ctx, rc.Param("id"))
}

The page and its stock box have a path in each locale, and so does the basket action:

  • The catalogue page is the one Links and locales registers.
  • addToBasket is the action's handler, as in Forms and actions.
  • static/ is mounted at /static/, as in Static assets.
  • The product is Required: a page without it has nothing to show.
layout := collage.NewFragment("layout", "layouts/master.html").Build()

stock := collage.NewFragment("product-stock", "fragments/stock.html").
	WithData(collage.Load(loadStock)).
	Build()

product := collage.NewPage("product").
	WithLayouts(layout).
	WithContent(collage.NewFragment("product", "pages/product.html").
		WithData(collage.LoadTagged(loadProduct)).
		WithSlotFragment("stock", stock).
		Required().
		Build()).
	WithPath("en", "/products/{id}").
	WithPath("tr", "/urunler/{id}").
	WithFragmentPath("en", "/products/{id}/stock", stock).
	WithFragmentPath("tr", "/urunler/{id}/stok", stock).
	Build()

if err := app.Register(catalogue, product); err != nil {
	return err
}
return app.RegisterAction(collage.NewAction("basket-add").
	WithPath("en", "/basket/{id}").
	WithPath("tr", "/sepet/{id}").
	WithMethods(http.MethodPost).
	WithHandler(addToBasket).
	Build())

The layout links the shop's stylesheet, marks the head's area and carries the language switcher:

<!-- templates/layouts/master.html -->
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="{{asset "/static/app.css"}}">
  {{hoist "head"}}
</head>
<body>
  <nav>
    {{with localeURL "en"}}<a hreflang="en" href="{{.}}">English</a>{{end}}
    {{with localeURL "tr"}}<a hreflang="tr" href="{{.}}">Türkçe</a>{{end}}
  </nav>
  {{slot "content"}}
</body>
</html>

The product's template names every page, fragment and action it links, and never writes a path:

<!-- templates/pages/product.html -->
{{stylesheet "/static/product.css"}}
<article class="product">
  <a href="{{pageURL "catalogue"}}">{{.Labels.Back}}</a>
  <h1>{{.Name}}</h1>
  <img src="{{asset .Image}}" alt="">
  <div data-live="{{fragmentURL "product" "product-stock" "id" .ID}}">{{slot "stock"}}</div>
  <form method="post" action="{{actionURL "basket-add" "id" .ID}}">
    {{csrfToken}}
    <button>{{.Labels.Add}}</button>
  </form>
</article>
<!-- templates/fragments/stock.html -->
<p class="stock">{{.}}</p>

What the reader gets

A request for /tr/urunler/42 answers 200. The page reads as follows, with blank lines left out and the token shortened:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="/static/app.6d6068180a5c710c.css">
  <title>Pirinç güverte lambası</title><link rel="stylesheet" href="/static/product.e38a7cd1dac68eec.css">
</head>
<body>
  <nav>
    <a hreflang="en" href="/products/42">English</a>
    <a hreflang="tr" href="/tr/urunler/42">Türkçe</a>
  </nav>
<article class="product">
  <a href="/tr/urunler">Tüm ürünler</a>
  <h1>Pirinç güverte lambası</h1>
  <img src="/static/products/42.04115f7d8dde41ce.svg" alt="">
  <div data-live="/tr/urunler/42/stok"><p class="stock">12</p>
</div>
  <form method="post" action="/tr/sepet/42">
    <input type="hidden" name="_csrf" value="…">
    <button>Sepete ekle</button>
  </form>
</article>
</body>
</html>

The same templates render /products/42 in English. The name and the labels come from the data; the URLs change with the render's locale:

In the templateOn /products/42On /tr/urunler/42
pageURL "catalogue"/products/tr/urunler
fragmentURL "product" "product-stock" "id" .ID/products/42/stock/tr/urunler/42/stok
actionURL "basket-add" "id" .ID/basket/42/tr/sepet/42
localeURL "en", localeURL "tr"/products/42, /tr/urunler/42the same
asset .Image/static/products/42.04115f7d8dde41ce.svgthe same
  • The title and product.css land at the marker, after app.css, which the layout writes above it. The title comes first: the handler declared it before the template ran.
  • asset takes a path from the data as readily as a literal one. A picture missing from the mount is ErrUnknownAsset, and since the product is required, the page answers 500 instead of showing a broken image.
  • The token is each reader's own. Were this page cached, the cached bytes would hold the placeholder, and every reader would get their own token in its place.