Core concepts27 min read

Data handlers

How a fragment fetches its data: the handler contract, dependency tags, 404s, concurrency, the render context, timeouts, and checking templates against data.

A data handler is the function a fragment calls to get what its template renders. It receives the request's context and the render context, and returns the data in a Go type of its own, the dependency tags that data came from, and an error.

Everything about a page that talks to the outside world — a database, a CMS, an API — happens in data handlers, and nowhere else.

content := collage.NewFragment("post", "pages/post.html").
	WithData(collage.LoadTagged(func(ctx context.Context, rc *collage.RenderContext) (*Post, []string, error) {
		post, err := store.Post(ctx, rc.Param("slug"))
		if err != nil {
			return nil, nil, err
		}
		return post, []string{"post:" + post.Slug}, nil
	})).
	Required().
	Build()

The contract

A fragment's data is set with WithData, which takes a collage.Data. Only four constructors make one, and each says where the data comes from:

ConstructorWhat it runsThe template's .
collage.LoadTagged(fn), fn returning (T, []string, error)fn, on every render, reporting its dependency tagsT
collage.Load(fn), fn returning (T, error)fn, on every render, reporting no tagsT
collage.Value(v)Nothing: v is handed over on every renderv's type
collage.Effect(fn), fn returning errorfn, on every render, for what it declaresNothing

A fragment with no WithData renders with no data, as one with collage.Effect does.

A handler is an ordinary function that returns its own type. Write it inline, as above, or name it and hand it over:

func loadPost(ctx context.Context, rc *collage.RenderContext) (*Post, []string, error) {
	// ...
}

content := collage.NewFragment("post", "pages/post.html").
	WithData(collage.LoadTagged(loadPost)).
	Build()

T comes from the function's signature, and it is the type the template is checked against when the page is registered — see How templates are checked — so the handler and the template's idea of its data cannot drift apart.

A loader written this way is also easy to call from a test or a sitemap's handler, which get a *Post rather than a value to assert. The constructors are functions of their own rather than forms of WithData because Go methods cannot take type parameters.

The three results of a LoadTagged each have a job.

  • The data — whatever the template renders, as .. A struct written for the template, a "view", is usually clearer than handing a template a database row. Each fragment gets its own; a child does not see its parent's. On an error the data is dropped, so a nil *Post returned beside an error never reaches the template as a value that looks present.
  • The tags — the pieces of content this data was built from, such as "post:hello-world" or "author:ada". They are collected from every fragment on the page, together with the page's own WithDependencyTags tags, and stored with the cached page, so invalidating a tag invalidates every page that showed it. Return nil when the data depends on nothing that changes. See Caching.
  • The error — a non-nil error fails the fragment, and the fragment's failure policy decides what that means for the page.
A data handler receives ctx and rc and returns three things. The data becomes the template's dot, and is dropped when there is an error. The tags join the page's tags, are kept when there is an error, and are stored with a cached page. The error goes to the fragment's failure policy: a required fragment fails the page with a 500, or a 404 when the error wraps ErrNotFound; a fragment with a fallback renders the fallback; any other renders nothing.ctx, rcdata handlerLoadTagged(fn)data: Ttagserrortemplate's .page's tagsfailure policydropped onan errorkept on an errorstored with acached pageRequired(): 500,ErrNotFound: 404WithFallback: fneither: nothing
A data handler is handed the request's context and the render context, and each of its three results goes somewhere else. The data becomes the template's .; on an error it is dropped. The tags join the page's own and are stored with the page when it is cached; on an error they are kept. The error goes to the fragment's failure policy: a Required() fragment fails the page with a 500, or a 404 when the error wraps collage.ErrNotFound; a fragment with a fallback renders it; any other renders nothing.

Tags are kept even when the handler returns an error. A handler that worked out what it depends on and then failed has still said what would invalidate the page.

A handler also decides how a page that declares no strategy is served. Such a page is dynamic when anything it renders has a data handler, and static otherwise: a handler may read the request, a cookie, the clock, and nothing outside the function can tell whether it does.

What to say instead depends on the handler's output:

The handler's outputSayWhat it does
Is the same for every reader — a post read from a fileStatic() or Incremental(ttl) on the page itselfThe page keeps the strategy it declares
Depends only on the path's parameters and the localeStatic() on the handler's fragmentLeaves every page using that fragment static
Is the same for every reader but changes over time — a measurementShared() on the fragmentIts render may be shared between readers, and the page stays dynamic

See Caching.

Fixed data: collage.Value

Data that is fixed when the program starts — a list of links, a heading, a site name — needs no handler. collage.Value(v) hands the template v on every render:

type homeView struct {
	Links []link
}

content := collage.NewFragment("home-content", "pages/home.html").
	WithData(collage.Value(homeView{Links: links})).
	Build()

Nothing in it fetches per render, so unlike a handler it leaves a page that declares no strategy static.

A fragment has one source of data. Calling WithData twice with data is refused at registration with collage.ErrConflictingData, whose message names the fragment: fragment "home-content" has its data set twice. Keep the call you mean and drop the other.

A nil Data — WithData(nil), or a constructor handed a nil function — is no data, and conflicts with nothing.

Handlers with no tags

collage.Load is LoadTagged for a loader that reports no tags, one that returns the data and an error:

func loadClock(_ context.Context, rc *collage.RenderContext) (clockView, error) {
	return clockView{Now: time.Now(), Locale: rc.Locale}, nil
}

content := collage.NewFragment("clock", "fragments/clock.html").
	WithData(collage.Load(loadClock)).
	Build()

A handler that reads through something the application builds once — a service, a store — is made by a function that takes it, and the fragment's own function passes it on, so nothing reaches for a global:

func Post(posts *blog.Service) *collage.Fragment {
	return collage.NewFragment("blog-post", "pages/blog-post.html").
		WithData(postData(posts)).
		Build()
}

func postData(posts *blog.Service) collage.Data {
	return collage.Load(func(ctx context.Context, rc *collage.RenderContext) (postView, error) {
		post, err := posts.BySlug(ctx, rc.Param("slug"))
		if err != nil {
			return postView{}, err
		}
		return postView{Title: post.Title}, nil
	})
}

collage add page and collage add fragment write the handler in this shape, with no parameters yet, so a service is one parameter added to both functions. In VS Code, the extension's cdata snippet writes one, returning the …View type the file declares.

Both drop the data when the loader returns an error. Which one to reach for:

The dataWrite
Is the same on every rendercollage.Value(v)
Is fetched, from content whose changes must reach a cached pagecollage.LoadTagged(fn)
Is fetched, with no tags to reportcollage.Load(fn)
Is nothing: the fragment only declares things for the pagecollage.Effect(fn) — see below

Leave out the tags only where the page is not cached or the data never changes: a cached page whose data changes wants its tags, so that they invalidate it. And moving from collage.Value to a handler changes more than the fragment — a page that declares no strategy goes from static to dynamic with it.

Not found is not an error

A missing record and a broken database are different failures, and a reader should get a different answer for each: a 404 for the first, a 500 for the second. Say which by wrapping collage.ErrNotFound:

func loadPost(ctx context.Context, rc *collage.RenderContext) (*Post, []string, error) {
	slug := rc.Param("slug")
	post, err := store.Post(ctx, slug)
	if errors.Is(err, sql.ErrNoRows) {
		return nil, nil, fmt.Errorf("blog: no post %q: %w", slug, collage.ErrNotFound)
	}
	if err != nil {
		return nil, nil, fmt.Errorf("blog: load post %q: %w", slug, err)
	}
	return post, []string{"post:" + slug}, nil
}

On a Required() fragment, an error wrapping collage.ErrNotFound renders the page's not-found page with a 404; any other error renders its error page with a 500. See Pages and layouts.

Two conditions, both easy to miss:

  • Wrap with %w all the way up. The framework checks with errors.Is, so a %v anywhere between your store and the handler's return turns the 404 into a 500.
  • Only a required fragment turns it into a 404. On an optional fragment it is an ordinary failure — the fragment renders nothing or its fallback — because the page is still worth showing without it.

When handlers run

A page's data handlers do not run one at a time. Before a fragment renders its template, the data handlers of every fragment in its slots start at once. A page made of a post, a sidebar and a comment list waits for the slowest of the three, not their sum.

The order that is guaranteed:

  • A parent's handler finishes before its children's start. A child can read what its parent stored under a key, and a path parameter its parent resolved.
  • Siblings run at the same time, each on its own goroutine, in no particular order.
  • Templates still render one at a time, in tree order. Output is identical from one request to the next, and anything that depends on order — which title wins in the <head>, say — is decided by the tree, not by which handler finished first: the innermost declaration wins, and at equal depth the one later in the page — within a slot, the fragment bound later; between slots, the one the template renders later.

That has three consequences for the code you write.

  • Handlers must be safe to run concurrently with their siblings. Anything they share — a map, a counter, a client that is not goroutine-safe — needs the same care it would anywhere else in Go.
  • Shared values go through a collage.Key, whose Get and Set hold the render's lock — see below.
  • A fragment in a slot the template does not render still starts. Its context is cancelled as soon as the template has finished, and its failure is discarded, as is everything it declared: it changes no title, meta or tags, and hoists nothing. A handler that is expensive and usually skipped belongs behind something other than a conditional in a template.

The render context

rc *collage.RenderContext is everything a handler knows about the request being rendered.

MemberWhat it gives you
rc.RequestThe *http.Request being answered. In a static export, a synthetic GET for the page's path
rc.LocaleThe locale the URL resolved to
rc.Param(name), rc.PathParamsWhat the route's {name} placeholders captured
rc.PageThe page being rendered; in an action, the page whose URL it answers on; in a fragment served at a URL its page opened for it, that page — read only
key.Get(rc), key.Set(rc, value)Values shared between the fragments of one render, through a collage.Key
rc.Context()The context the render context carries
rc.HoistTitle, rc.HoistMeta, rc.HoistProperty, rc.HoistLink, rc.HoistAlternate, rc.HoistStylesheet, rc.HoistDeclarations for the page's <head> — see Head and SEO
rc.Asset(path)A mounted file's content-addressed URL — see Static assets
rc.URL(name, params), rc.ActionURL(name, params)A page's or an action's URL by name, in the render's locale — see Links from Go

Inside a handler, rc.Context() is the same context as the ctx argument, with the fragment's timeout on it. Use ctx; it is the one already in hand.

Two rules about the render context itself.

  • Do not keep it. It belongs to one render. Holding it past the handler's return — in a goroutine, a cache, a struct — is holding on to a request that has finished.
  • Do not write to rc.Page. It is the one registered *collage.Page, shared by every request rendering that page at the same moment. Writing to its Paths map or its DependencyTags from a handler is a data race on live framework state, which go test -race reports and production eventually corrupts. Anything that varies per request goes in the data you return or under a collage.Key.

Sharing data between fragments

Fragments on one page often need the same thing. The post page's content, its <head> and its "more by this author" box all want the post.

collage.Key

A collage.Key is a name and a type, declared once at package level. Set stores a value under it for the rest of the render, and Get reads it back as that type:

var postKey = collage.NewKey[*Post]("post")

// in the parent's handler
postKey.Set(rc, post)

// in a child's handler, which starts after the parent's has returned
post, ok := postKey.Get(rc)
if !ok {
	return nil, nil, errors.New("more-by-author: no post stored under postKey")
}

ok is false when nothing is stored under the key. A read needs no type assertion, and a write of the wrong type does not compile.

A key is its name and its type: NewKey[*Post]("post") and NewKey[*Draft]("post") are two keys holding two values, and two NewKey[*Post]("post") declared in different files are one. Keys are your application's own namespace; pick names that will not collide.

With derives a key per value from a declared one: postKey.With(slug) is named post:<slug> and holds the same type, and it chains, boardKey.With(id).With("filter"). A part's : and \ are escaped, so With("b:c") and With("b").With("c") are two keys; a part without them keeps its name as written. NewKey panics on an empty name, at the line that declares it, and a zero Key — a struct field never made with NewKey — panics where it is used.

Get and Set take the render's lock, which is why they are safe from concurrent siblings.

This works from parent to child, because a parent's handler finishes first. It does not work between siblings: they run at the same time, so one cannot count on the other having set anything yet. Nor does it work in a fragment answered at its own URL, or pushed: it renders without its ancestors, so their Set never happens there. Load the value in the fragment with collage.Once.

collage.Once

For siblings — or any fragments that might each need the same fetch — use collage.Once. It runs a fetch at most once per render for a key, and hands the result to every fragment that asks:

func loadAuthorCard(ctx context.Context, rc *collage.RenderContext) (Author, []string, error) {
	slug := rc.Param("slug")
	post, err := collage.Once(rc, postKey.With(slug), func(ctx context.Context) (*Post, error) {
		return store.Post(ctx, slug)
	})
	if err != nil {
		return Author{}, nil, err
	}
	return post.Author, []string{"post:" + slug, "author:" + post.Author.ID}, nil
}

The first caller fetches; the rest wait for it and receive what it produced. The obvious alternative — Get, fetch on a miss, Set — has a gap between the check and the write, and two siblings both fall into it and both fetch.

  • An error is a result. Everyone waiting gets it; the fetch is not retried per fragment, which is how one slow failure would become several.
  • Except a cancellation. A fetch that failed only because the context of the fragment that ran it ended — a speculative prefetch for a slot the template did not render, say — says nothing about the key: the next caller fetches again rather than failing with it.
  • A panic releases everyone. A fetch that panics frees the fragments waiting on it at once, each with an error saying so, and the panic goes to the fragment whose fetch it was, which fails as a *collage.PanicError.
  • It lasts one render. There is nothing to configure and nothing to evict.
  • A waiter whose own context ends stops waiting and returns that error.
  • Its values are its own. What Once fetched is not readable with Get, and what Set stored is not handed to Once. Two keys of one name and different types are two fetches.

collage.Cached

Once shares work within a page. collage.Cached shares it between pages and between requests: thirty posts by one author fetch the author once.

var authorKey = collage.NewKey[Author]("author")

author, err := collage.Cached(rc, authorKey.With(id), time.Hour, []string{"author:" + id},
	func(ctx context.Context) (Author, error) { return api.Author(ctx, id) })

Its tags are added to the page's own, and invalidating one marks both the stored value and every cached page built from it stale. Where nothing is kept across renders — caching off, development, a preview — it behaves exactly like Once. The details are in Caching.

It is also the one to reach for when fragments are refreshed separately. Each fragment path is a render of its own, so Once shares nothing between two of them; Cached does.

Handlers that render nothing

Some fragments exist to declare things for the page rather than to render markup: a title, a canonical link, structured data. collage.Effect adapts a handler that returns only an error:

seo := collage.NewFragment("post-seo", "fragments/empty.html").
	WithData(collage.Effect(func(ctx context.Context, rc *collage.RenderContext) error {
		post, err := collage.Once(rc, postKey.With(rc.Param("slug")), func(ctx context.Context) (*Post, error) {
			return store.Post(ctx, rc.Param("slug"))
		})
		if err != nil {
			return err
		}
		rc.HoistTitle(post.Title)
		rc.HoistMeta("description", post.Summary)
		return nil
	})).
	Build()

The fragment's template receives no data, and the handler reports no tags. When what it declares comes from content that changes and the page is cached, that content's tags still have to reach the page: return them from an ordinary handler instead, or add them with WithDependencyTags on the page.

A title known when the program starts — the site's name, on its layout — needs no handler at all. WithTitle(s) on the fragment declares it, and leaves a page that declares no strategy static. It counts at its fragment's place in the page exactly as a handler's HoistTitle would, so a more specific fragment's title still wins over it; see Head and SEO.

Example: a catalogue product page

A shop's product page at /products/{id} draws on three services, and each piece of data is fetched in the way that suits it:

DataComes fromFetched with
Name and brand idThe catalogueThe product's handler, on every render
PriceA pricing serviceThe same handler, after the catalogue
Brand: name and countryThe catalogue, a slow lookup many products sharecollage.Cached, for a day, tagged brand:<id>
ReviewsA reviews servicecollage.Once, from two sibling fragments: the reviews box and the page's description

The catalog, pricing and reviews packages stand for your own clients. The product's handler:

var (
	brandKey   = collage.NewKey[catalog.Brand]("brand")
	reviewsKey = collage.NewKey[reviews.Summary]("reviews")
)

type productView struct {
	Name  string
	Price string
	Brand catalog.Brand
}

func loadProduct(ctx context.Context, rc *collage.RenderContext) (productView, []string, error) {
	id := rc.Param("id")
	p, err := catalog.Product(ctx, id)
	if errors.Is(err, catalog.ErrNoProduct) {
		return productView{}, nil, fmt.Errorf("shop: no product %q: %w", id, collage.ErrNotFound)
	}
	if err != nil {
		return productView{}, nil, fmt.Errorf("shop: load product %q: %w", id, err)
	}
	price, err := pricing.Price(ctx, id)
	if err != nil {
		return productView{}, nil, fmt.Errorf("shop: price of %q: %w", id, err)
	}
	// Many products share a brand: one fetch serves all of them.
	brand, err := collage.Cached(rc, brandKey.With(p.BrandID), 24*time.Hour, []string{"brand:" + p.BrandID},
		func(ctx context.Context) (catalog.Brand, error) { return catalog.LookupBrand(ctx, p.BrandID) })
	if err != nil {
		return productView{}, nil, fmt.Errorf("shop: brand %q: %w", p.BrandID, err)
	}
	return productView{Name: p.Name, Price: price, Brand: brand}, []string{"product:" + id, "price:" + id}, nil
}
  • An unknown id is a 404. The handler wraps collage.ErrNotFound, and its fragment is Required(), so the reader gets the not-found page. Any other error fails the page with a 500.
  • The brand is fetched once for all its products. The brand:<id> tag joins the page's tags as if the handler had returned it, so the handler returns only product:<id> and price:<id>.

The reviews are wanted twice: by the reviews box, and by a fragment that puts the rating in the page's description. Both call one function:

// reviewsOf is called by two sibling fragments; Once makes it one call per render.
func reviewsOf(rc *collage.RenderContext, id string) (reviews.Summary, error) {
	return collage.Once(rc, reviewsKey.With(id), func(ctx context.Context) (reviews.Summary, error) {
		return reviews.For(ctx, id)
	})
}

func loadReviews(ctx context.Context, rc *collage.RenderContext) (reviews.Summary, []string, error) {
	id := rc.Param("id")
	summary, err := reviewsOf(rc, id)
	if err != nil {
		return reviews.Summary{}, nil, err
	}
	return summary, []string{"reviews:" + id}, nil
}

func productSEO(ctx context.Context, rc *collage.RenderContext) error {
	summary, err := reviewsOf(rc, rc.Param("id"))
	if err != nil {
		return err
	}
	rc.HoistMeta("description", fmt.Sprintf("Rated %.1f out of 5 in %d reviews.", summary.Average, summary.Count))
	return nil
}

The two fragments are siblings, so their handlers start together. Whichever reaches reviewsOf first calls the reviews service, and the other waits for its result. A Get, a fetch on a miss and a Set could have called it twice.

The product binds both into its slots:

reviewsBox := collage.NewFragment("product-reviews", "fragments/reviews.html").
	WithData(collage.LoadTagged(loadReviews)).
	WithTimeout(500 * time.Millisecond).
	Build()

seo := collage.NewFragment("product-seo", "fragments/empty.html").
	WithData(collage.Effect(productSEO)).
	WithTimeout(500 * time.Millisecond).
	Build()

content := collage.NewFragment("product", "pages/product.html").
	WithData(collage.LoadTagged(loadProduct)).
	WithSlotFragment("reviews", reviewsBox).
	WithSlotFragment("seo", seo).
	Required().
	Build()

page := collage.NewPage("product").
	WithLayouts(layout).
	WithContent(content).
	WithPath("en", "/products/{id}").
	Incremental(10 * time.Minute).
	Build()
<!-- templates/pages/product.html -->
<article>
  <h1>{{.Name}}</h1>
  <p class="price">{{.Price}}</p>
  <p class="brand">{{.Brand.Name}}, {{.Brand.Country}}</p>
  {{slot "reviews"}}
</article>
{{slot "seo"}}

The description lands where the layout's {{hoist "head"}} marker is — see Head and SEO. Both fragments get the same timeout because the one call runs under the context of whichever fragment asked first.

Once and Cached side by side. Left, Once: in one render, the sibling fragments reviews and seo both ask for the key reviews:42, and one call serves both; the next render calls again. Right, Cached: the renders of product 42 and product 43 both ask for the key brand:acme, and one call is kept in the data cache, fresh for 24 hours or until brand:acme is invalidated.Onceone renderreviewsseoreviews:42one call, sharednext render:called againCachedrender ofproduct 42render ofproduct 43brand:acmedata cache: one callfresh 24 h, or untilbrand:acme invalidated
Once shares a call between the fragments of one render, Cached between renders. On the product page the reviews box and the description share one call to the reviews service per render, and every product of one brand shares one brand lookup. Where nothing is kept across renders (caching off, development, a preview) Cached behaves like Once.

What each failure does to this page:

  • There is no product 7. The required fragment's error wraps collage.ErrNotFound: the not-found page, with a 404.
  • The catalogue or the pricing service fails. The product is required, so the page's error page is served with a 500.
  • The brand lookup fails. With no brand stored yet, that is a 500 too. With a stale one stored, Cached serves it instead, and the page, built from stale data, is not cached.
  • The reviews service is down, or slower than 500 milliseconds. Its one call fails, and both fragments get that error: the reviews box renders nothing, no description is declared, and the page answers 200 without them. A page served with a failed fragment is degraded and never cached, so the next request asks the reviews service again — unless the page cache still holds an older copy, which is then served marked STALE.

With the cache on, none of this runs while the page is fresh: a cached page is not rendered, so the next reader of /products/42 within ten minutes costs no call at all. See Caching.

Timeouts and the context

Every data handler runs under a deadline: the fragment's WithTimeout(d), or Config.Template.Timeout — five seconds by default — for a fragment that sets none.

The deadline is on the ctx the handler receives. It bounds the context, not the handler.

The framework does not abandon a handler at its deadline; it waits for it to return, because a goroutine cannot be stopped from outside, and abandoning handlers that never return would leak one goroutine per request, forever. So a handler that ignores its context can run past its deadline, and the page waits for it.

Honouring it is one habit: pass ctx to everything that can wait.

func loadWeather(ctx context.Context, rc *collage.RenderContext) (*Weather, []string, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, weatherURL(rc.Locale), nil)
	if err != nil {
		return nil, nil, err
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, nil, err // context.DeadlineExceeded when the timeout passed
	}
	defer res.Body.Close()

	var weather Weather
	if err := json.NewDecoder(res.Body).Decode(&weather); err != nil {
		return nil, nil, err
	}
	return &weather, nil, nil
}

A handler that returns its context's error when time runs out fails like any other, with an error that still matches errors.Is(err, context.DeadlineExceeded). The deadline is only an error if the handler says so: one that ignores ctx and returns nil late has succeeded, and its data renders.

Pair a short timeout with a fallback on anything that is nice to have, and the page stops waiting on a slow service at the point you chose.

The error says which deadline it was. Only the fragment's own timeout is reported as one — collage: execution exceeded 5s — and a context that ended above it, a request cancelled or a shorter deadline, is reported as collage: execution stopped by context, with its cause when it has one, so a cancelled request does not send you looking for a handler that was never slow.

Panics

A panic in a data handler does not take the process down. It is recovered into a *collage.PanicError, carrying the panic value and the stack, and the fragment fails with it like any other error. In development the error page shows the stack; reach it in your own code with errors.As.

How templates are checked

A template reads its data by name — {{.Title}}, {{.Author.Name}} — and html/template resolves those names only when the template runs. A {{.Titel}} fails every render of its page, and on a page nobody visits, it never shows.

Every fragment's data comes from a typed constructor, so registration knows the Go type each template will run with and walks the template against it. RegisterPage refuses a page whose templates do not fit their data, naming the page, the fragment, the file, the line and the column:

collage: page "post": fragment "post-body" (post.html:1:6): {{.Titel}}: type blog.Post has no field or method Titel (did you mean Title?)

It reports only what is certain to fail: each finding is an expression text/template would fail on when the render reached it. A template the check refuses would have failed when rendered; the check reports it earlier, and adds no rule of its own.

Escaping is checked at registration too, beside the types: every fragment's root template is escaped once, as its first render would escape it, and a template html/template cannot escape — a <script> string that never closes, {{if}} branches that leave an attribute in different states — is refused, naming the page, the fragment and the template. WithoutTypeCheck() does not turn that off. See Templates.

What is walked

Every fragment a page reaches: its layouts, its content, everything bound into their slots, fallbacks, inline fragments, fragments opened with WithFragmentPath, and the pages named as its not-found and error pages. A partial included with {{template "partials/author.html" .Author}} is walked with the type it is handed, and once for each type it is handed across the application.

A fragment a slot resolver returns is built while the page renders, so registration never sees it, and its template is not checked.

. starts as the fragment's data type and follows the template: inside {{range}} it is the element, inside {{with}} the value, and a $x := … variable keeps the type it was given for its scope.

What is reported

  • A field or method the type does not have, or a field that is unexported. Pointers are followed, and fields promoted from embedded structs count. The closest exported name is suggested when one is near.
  • A method with a pointer receiver, reached through a value that is not addressable.text/template calls such a method through the value's address, and data handed to a template by value has none — nor have its fields, nor a map's elements. What a pointer points to and a slice's elements are addressable. If URL is declared on *Post, {{.URL}} fails on a Post and works on a *Post; the fix is to hand the template the pointer.
  • A map keyed by a named string type (map[Slug]Post): .key looks a key up as a plain string, which such a map does not accept. A map keyed by string is fine, and a key it does not hold is not an error either: it silently ends the chain, so {{.Meta.absent.Name}} renders nothing. The check, knowing only the map's element type, still reports a name that element type lacks.
  • Calls of the wrong shape: a method, a template function or a built-in given the wrong number of arguments; a field or map key given arguments; a method or function returning more than a value and an error; call on something that is not a function.
  • range, len, index and slice on the wrong kind: ranging over a string or a struct, or over an integer with two variables; len of a struct; index into a struct; slice of anything but a string, a slice or an array, of a string by three indexes, or of an array text/template cannot take the address of ({{slice .Days 0}} on data passed by value: pass the pointer). A slice, array or string is indexed and sliced by integers, and a map by a key of its own key type: {{index .ByID "7"}} on a map[int]Post is reported.
  • Number constants, typed as text/template types them: 1 is an int, 1.5 a float64, 1i a complex128, 'a' an int. So {{(1.5).Nope}} and {{len 1}} are reported, as are a constant too large for an int and nil used as a command.
  • An argument its parameter cannot take, judged as text/template judges it when it calls a template function or a method:
    • a constant by the parameter's kind: an integer parameter takes a number written as an integer, an unsigned one a non-negative integer, a float one any number but a complex one, a string or bool one a string or a bool. So {{upper 1}}, {{printf 1}}, {{uint -1}} and {{i8 1.5}} are reported, and nil goes only where a nil can;
    • any other value must be assignable to the parameter, or be a pointer to something that is, or be addressable where the parameter is its pointer. So {{upper .Count}} with an int field and {{edit .Owner}} for a func(*User) on data passed by value are reported, while {{show .Author}} for a func(User) with a *User field is fine. A variadic parameter takes its element type, and the value piped in, {{.Count | upper}}, is judged like any other argument;
    • call checks what it passes as text/template's call does: a value assignable to the parameter, or an integer converted to another integer type, and nothing else.

What the render can never reach is not reported. An {{if}} or {{with}} whose condition is a literal — true, false, 0, 1, "", "x", or not of one — never runs the side the literal rules out, even when the condition declares or assigns a variable: {{if $x := false}}{{.Nope}}{{end}} reports nothing. {{and}} and {{or}} stop at an operand only when it is a literal that decides them: false, 0, "" or nil for and; true, a non-zero number or a non-empty string for or. So {{and 0 .Nope}} reports nothing, while {{and 1 .Nope}} and {{and .Title .Nope}} report .Nope, since the render may reach it.

What is not

  • What cannot be known before the render. An interface — any, a map[string]any's entries, an error — could hold anything, so nothing read from one is reported. Nor is anything read from a reflect.Value that a method or function returns, which text/template unwraps into whatever it holds.
  • A fragment with no data. Reading a field of nil data is not an error in html/template: {{.Title}} renders nothing. A fragment without WithData, or with collage.Effect, is still walked, but only its function calls are checked: their argument counts, and the arguments not read from ..
  • Nil pointers inside the data.{{.Author.Name}} with a nil Author fails when it renders, and whether it is nil is the data's business, not the type's.
  • An argument whose fit the render decides. A value of an interface type, a reflect.Value, a parameter of type any or reflect.Value, and a map entry handed to a parameter that can be nil (a key the map does not hold arrives as nil, which that parameter takes) are not judged. Nor are the arguments of a method of a value read by a map key, which the render never calls when the key is missing, nor an index out of range. A plugin's render functions take anything as far as the check knows, so their arguments are left to the plugin.
  • An integer constant's range.text/template converts a constant to an integer parameter without a range check, so {{i8 300}} renders 44 rather than failing.

Reading the error

RegisterPage returns every finding in the page's own fragments at once, joined with errors.Join and ordered by file, line and column, so ten mistakes are one restart rather than ten. The page's not-found page is checked once the page itself passes, and its error page once both have; their findings arrive wrapped in a collage: page "post" not-found page: … (or error page: …) error, on the start after the page's own are fixed.

Each finding is a *collage.TemplateTypeError, and each matches collage.ErrTemplateType. A finding may sit under a wrapping error as well as a join, so walk the whole tree to list them:

// typeErrors collects every *collage.TemplateTypeError in err's tree.
func typeErrors(err error) []*collage.TemplateTypeError {
	switch e := err.(type) {
	case nil:
		return nil
	case *collage.TemplateTypeError:
		return []*collage.TemplateTypeError{e}
	case interface{ Unwrap() []error }:
		var found []*collage.TemplateTypeError
		for _, inner := range e.Unwrap() {
			found = append(found, typeErrors(inner)...)
		}
		return found
	case interface{ Unwrap() error }:
		return typeErrors(e.Unwrap())
	}
	return nil
}

and, where the page is registered:

if err := app.RegisterPage(page); errors.Is(err, collage.ErrTemplateType) {
	for _, typeErr := range typeErrors(err) {
		fmt.Printf("%s:%d:%d %s\n", typeErr.Template, typeErr.Line, typeErr.Col, typeErr.Reason)
	}
}

errors.As on the returned error finds the first finding. Its fields:

FieldWhat it holds
Page, FragmentThe page and the fragment the template belongs to
TemplateThe file the expression is in — the fragment's own, or a partial it includes — or inline template of fragment "x"
Line, ColWhere text/template itself would name the error, which may lie inside Expr rather than at its start: at the last argument of a call, say
ExprThe expression as written, {{.Titel}}
ReasonWhat is wrong
SuggestionThe closest name the type has, or empty

The check runs where the other registration checks run: at startup, and so in collage check, which starts the application, and in a test that registers the pages.

Under collage dev a template edited while the program runs is reparsed but not checked again until the next restart, which is the next change to its Go code. collage inspect prints each fragment's data type, and the types it reaches, for an editor to check the same way.

Turning it off

WithoutTypeCheck() leaves one fragment's template out of the check, for the rare finding that is wrong, while it is fixed. The fragment renders as before, and collage inspect marks it "typeCheck": false:

collage.NewFragment("post-body", "pages/post.html").
	WithData(collage.LoadTagged(loadPost)).
	WithoutTypeCheck().
	Build()

A handler declared to return an interface — collage.Load[any], say — leaves the type unknown, and its template is not walked: that is the way to say on purpose that a fragment's data has no fixed shape. collage.Value is the exception. Its value is in hand, so a value held in an interface is checked against the type it holds.