Core concepts16 min read
Fragments and slots
Fragments, the slots they expose, what happens when one fails, and slots filled from content at render time.
A fragment is the unit a page is made of. It has three parts:
- a template;
- an optional data handler that fetches what the template renders;
- named slots where other fragments go.
A layout is a fragment. So is the content of a page, a sidebar, an author card, a comment list. A page is a tree of them, with the layout at the root.
content slot holds the product, and the product's template calls two slots of its own. Each fragment has its own failure policy: the product is required, so its failure fails the page; the stock box has none, so it is left out; the similar products have a fallback. The whole page is built in Example: a product page.author := collage.NewFragment("author", "fragments/author.html").
WithData(collage.LoadTagged(loadAuthor)).
WithTimeout(time.Second).
WithFallback(anonymousAuthor).
Build()
Building a fragment
collage.NewFragment(name, templatePath) starts a builder, and Build() returns the *collage.Fragment.
- The name is how the fragment is reported: in error messages, in the development error panel, in render metadata and traces. Make it say which part of the page it is —
"post-comments", not"list". - The template path is relative to the template root, extension included:
"fragments/author.html"istemplates/fragments/author.html. A path the template engine did not load isErrTemplateNotFoundwhen the page holding the fragment is registered — including a fragment the page opens at its own URL withWithFragmentPath. Only a fragment a slot resolver returns is checked later, when it renders. See Templates.
Everything else is optional:
| Method | What it sets |
|---|---|
WithData(d) | The template's data: a handler from collage.LoadTagged or collage.Load, a value fixed when the program starts from collage.Value, or collage.Effect — see Data handlers |
WithoutTypeCheck() | Leaves the template out of the check against its data's type — see How templates are checked |
WithTitle(s) | The page's <title>, without a handler — see Head and SEO |
WithSlot(name, rules...) | Makes a slot required, or limits it to one fragment |
WithSlotFragment(slot, child) | Binds a child fragment into a slot |
WithSlotResolver(slot, resolve) | Fills a slot per render instead |
Required() | This fragment's failure fails the page |
WithFallback(f) | What renders when this fragment fails |
WithTimeout(d) | How long its data handler may take |
Static() | Its data handler returns the same for every request to one URL, so it does not make a page dynamic |
Shared() | Its data handler returns the same for every reader at one moment, though not over time, so its render may be sent to many readers; the page's strategy is left alone |
Like the page builder, the fragment builder records mistakes rather than stopping the chain, and BuildErr() returns them.
What it recorded stays on the fragment it built. So every one of them — a slot constrained twice, a second child bound into a slot limited to one, a negative timeout — stops any page whose tree contains the fragment at registration, whether or not anyone called BuildErr(). Call it when you want the error at the line that caused it rather than at RegisterPage; see Pages and layouts.
A fragment with no data handler renders its template with no data, or with the value collage.Value(v) hands it on every render. That is right for markup that never changes — a footer, a static notice, a list of links — and for a layout whose only job is to arrange slots.
It also keeps the page cacheable: a page that declares no strategy is static unless something it renders has a data handler or a slot resolver — see Caching. Two promises change how a handler counts:
- A fragment whose handler reads only the path's parameters and the locale says
Static(), and its handler no longer counts. - One whose handler is the same for every reader but not over time — a measurement — says
Shared(), which implies nothing about the page and still counts.
A handler that breaks either promise sends one reader's data to another. Setting a fragment's data twice is ErrConflictingData at registration.
Inline templates
A small fragment can carry its template itself instead of naming a file. collage.NewInlineFragment(name, html) returns the same builder, so the rest of the chain is unchanged:
row := collage.NewInlineFragment("post-row", `
<tr>
<td>{{.Title}}</td>
<td>{{template "partials/date.html" .Date}}</td>
</tr>`).
WithData(collage.LoadTagged(loadRow)).
Build()
It renders as a file template does — slots, hoist, every template function, {{template}} calls into the template directory. Registration parses and checks it like one: a parse error, a template html/template cannot escape or a slot it never calls stops startup, naming the page and the fragment.
Two fragments may share a name and still carry different templates; each renders its own. The development error panel names it as inline template of fragment "post-row".
A longer template can be a constant of its own, declared as collage.InlineHTML — a name for string that the VS Code extension colours and edits as HTML:
const loginForm collage.InlineHTML = `
<form method="post">
{{csrfToken}}
<input type="email" name="email" required>
</form>`
content := collage.NewInlineFragment("login", loginForm).Build()
Use it for the parts of a page that are a few lines of markup next to the handler that feeds them — a table row, a button, a form field. Layouts and whole pages read better as files.
The template is code, so it must be a constant. Never build it from data — NewInlineFragment("row", "<p>"+post.Title+"</p>") runs whatever {{…}} the title holds, and each distinct string becomes a template the program keeps until it exits.
This matters most in a slot resolver, which builds fragments per request: its fragments can be inline, but their templates are fixed, and the data reaches them through collage.Value or a data handler. The engine takes in at most 256 distinct inline templates from resolvers' fragments while the program runs; the next fails its fragment with collage.ErrTooManyInlineSources — a template must be fixed, not built from request data — rather than growing the template set a request at a time.
Three more limits come with it:
- A Go raw string cannot hold a backtick, so a template with a JavaScript template literal stays in a file.
- An inline template cannot
{{define}}or{{block}}templates of its own —ErrSourceConflictat registration — because a definition would replace a file template of that name for every page. - Calling an inline template from a file template with
{{template}}is not supported: its name in the template set is internal.
A fragment names a file or carries a template, never both (ErrConflictingTemplate), and an empty template is ErrEmptyTemplatePath. collage inspect marks an inline fragment with "inline": true and leaves its template empty.
Slots
A slot is a named position in a fragment's template, written {{slot "name"}}. Calling it in the template is all the declaring it needs; the fragment binds children into it by name:
post := collage.NewFragment("post", "pages/post.html").
WithData(collage.LoadTagged(loadPost)).
WithSlot("author", collage.SlotRequired, collage.SlotSingle).
WithSlotFragment("author", author).
WithSlotFragment("related", relatedPosts).
WithSlotFragment("related", popularPosts).
Build()
<!-- templates/pages/post.html -->
<article>
<h1>{{.Title}}</h1>
{{slot "author"}}
<div class="body">{{.Body}}</div>
</article>
<aside>{{slot "related"}}</aside>
A slot holds any number of fragments, rendered in the order they were bound, one after another; related above holds two. A slot nothing is bound to renders nothing. A layout's "content" slot needs no declaring either: registration puts a page's content into it.
WithSlot(name, rules...) is for when that is not what you want — author above must be filled, and holds one. It may come before or after the bindings it constrains. A rule is a collage.SlotRule:
collage.SlotRequired— the slot must have something in it. A required slot with nothing bound is refused at registration (ErrRequiredSlotUnfilled), and checked again before the template runs, so it is caught even if the template never asks for it.collage.SlotSingle— the slot holds one fragment at most. Binding a second recordsErrSlotOccupied.
Any other value records ErrInvalidSlotDefinition.
WithSlotFragment records ErrNilFragment for a nil child. Calling WithSlot twice with one name records ErrDuplicateSlot.
In the template, {{slot "name"}} renders what the slot holds as HTML, which is not escaped again: the children escaped their own values when they rendered.
A typo on either side of a binding — WithSlotFragment("sidbar", ...) against {{slot "sidebar"}} — fails registration with ErrUnknownSlot, naming the slot and the slots the template does call: a fragment bound into a slot its template never calls could never render.
Calls in a template it includes, or a block it defines, count. A template that names a slot by anything but a literal, {{slot .Which}}, may call any of them, so its fragment's bindings are not checked.
Each fragment has its own data
A child does not see its parent's data. Inside fragments/author.html, . is what loadAuthor returned, not the post. A child that needs something its parent fetched reads it through a collage.Key its parent set, or asks for it itself with collage.Once or collage.Cached so it is fetched only once — see Data handlers.
Reusing fragments
A *collage.Fragment can be bound into many slots on many pages; author above could appear on the post page and on a search result page. A fragment bound twice renders twice, running its data handler once per binding.
A fragment must not contain itself. Binding one, directly or through a chain of children, into its own slot is refused at registration with ErrFragmentCycle.
When a fragment fails
A fragment fails when:
- its data handler returns an error;
- its template fails to execute;
- a required slot is empty;
- either panics — a panic in a data handler or a template function is recovered into a
*collage.PanicErrorand treated as a failure, not a crashed process.
What happens next is the fragment's failure policy, and there are three.
postContent := collage.NewFragment("post", "pages/post.html").
WithData(collage.LoadTagged(loadPost)).
Required().
Build()
comments := collage.NewFragment("comments", "fragments/comments.html").
WithData(collage.LoadTagged(loadComments)).
WithFallback(collage.NewFragment("comments-unavailable", "fragments/comments-unavailable.html").Build()).
Build()
related := collage.NewFragment("related", "fragments/related.html").
WithData(collage.LoadTagged(loadRelated)).
Build()
Required()— the fragment's failure fails the page. Use it for what the page exists to show. The page's error page is served with a 500 — or, when the error wrapscollage.ErrNotFound, its not-found page with a 404. The failure travels through any optional fragments above it: a required fragment inside an optional sidebar still fails the page.WithFallback(f)—frenders in its place. If the fallback fails too, the fragment renders nothing and the page still succeeds: a fallback exists to contain a failure, so its own failure is contained as well, even if something inside it is marked required.- Neither — the fragment renders nothing, and the page is served without it.
Whichever it is, what a failed fragment hoisted leaves with its markup: its title, meta tags and stylesheets never reach the page, so a fallback does not render under the failed fragment's title. Its dependency tags stay, since they say what the page depended on.
collage.ErrNotFound only means "404" on a required fragment. On an optional one it is a failure like any other, because the page is still renderable without it.
A page served with any failed fragment, fallback or not, is degraded. It is sent to the reader but never cached, so the next request tries again rather than serving the failure for a TTL. A static export does not write a degraded page unless it is told to.
In development a failure is never quiet:
- A failed fragment that renders nothing leaves an HTML comment with its name and error where its output would have been.
- The page carries a panel naming every fragment that failed, with the error — for a template, the file and line — even when a fallback covered for it.
- When a required fragment fails the whole page, the development error page names that fragment — where the failure started, not the layout it travelled up through.
Outside development there is neither.
In every mode, a failure the page is served without is logged as a warning through Config.Logger: collage: fragment failed; the page is served without it, with the page, the fragment, the locale, whether a fallback covered for it, and the error.
Such a page still answers 200, so in production the log is where a missing form shows.
A slot the template skips
A fragment's children start fetching before its template runs, so that they fetch at the same time rather than one after another.
That means a fragment in a slot the template decides not to render — {{if .ShowComments}}{{slot "comments"}}{{end}} — still had its handler started. Its context is cancelled as soon as the template is done, and its failure is discarded: a fragment that was never rendered cannot fail the page, even if it is Required().
What it declared is discarded with it. It changes nothing about the page: not its title, its meta tags or its dependency tags — neither those its handler returned nor those of its collage.Cached calls — and it hoists nothing. A value it stored with Key.Set is not rolled back, so read such a value only from a fragment that is rendered.
Timeouts
WithTimeout(d) bounds the fragment's data handler. A fragment that sets none gets Config.Template.Timeout, which defaults to five seconds; a negative duration records ErrInvalidTimeout.
recommendations := collage.NewFragment("recommendations", "fragments/recommendations.html").
WithData(collage.LoadTagged(loadRecommendations)).
WithTimeout(300 * time.Millisecond).
WithFallback(nothingToRecommend).
Build()
A timeout pairs naturally with a fallback. A slow recommendation service costs the page 300 milliseconds and a fallback, rather than the reader's patience.
The timeout bounds the context the handler receives, not the handler: a handler that ignores ctx runs as long as it likes. Pass ctx to every call that can wait — see Data handlers.
Example: a product page
A shop's product page shows three things, and they matter differently:
| Part | Comes from | When it fails |
|---|---|---|
| The product: name, price, description | The catalogue | The page has nothing to show: Required() |
| A stock box: "12 in stock" | A stock service that is sometimes down | Leave the box out; no policy |
| "Similar products" | The catalogue | Show a link to the catalogue instead: WithFallback |
The handlers read the product's id from the path. The catalogue and inventory packages stand for your own data layer:
type product struct {
ID string
Name string
Price string
}
type stockLevel struct {
Count int
}
func loadProduct(ctx context.Context, rc *collage.RenderContext) (product, []string, error) {
id := rc.Param("id")
p, err := catalog.Product(ctx, id)
if errors.Is(err, catalog.ErrNoProduct) {
return product{}, nil, fmt.Errorf("catalog: no product %q: %w", id, collage.ErrNotFound)
}
if err != nil {
return product{}, nil, err
}
return product{ID: p.ID, Name: p.Name, Price: p.Price}, []string{"product:" + id}, nil
}
func loadStock(ctx context.Context, rc *collage.RenderContext) (stockLevel, error) {
n, err := inventory.Count(ctx, rc.Param("id"))
if err != nil {
return stockLevel{}, err
}
return stockLevel{Count: n}, nil
}
func loadSimilar(ctx context.Context, rc *collage.RenderContext) ([]product, []string, error) {
list, err := catalog.Similar(ctx, rc.Param("id"))
if err != nil {
return nil, nil, err
}
return list, []string{"catalog"}, nil
}
Each part is a fragment with its own policy, and the product binds the other two into its slots:
stock := collage.NewFragment("product-stock", "fragments/stock.html").
WithData(collage.Load(loadStock)).
WithTimeout(300 * time.Millisecond).
Build()
similar := collage.NewFragment("similar-products", "fragments/similar.html").
WithData(collage.LoadTagged(loadSimilar)).
WithFallback(collage.NewFragment("browse-catalogue", "fragments/browse-catalogue.html").Build()).
Build()
content := collage.NewFragment("product", "pages/product.html").
WithData(collage.LoadTagged(loadProduct)).
WithSlotFragment("stock", stock).
WithSlotFragment("similar", similar).
Required().
Build()
page := collage.NewPage("product").
WithLayouts(layout).
WithContent(content).
WithPath("en", "/products/{id}").
Build()
<!-- templates/pages/product.html -->
<article>
<h1>{{.Name}}</h1>
<p class="price">{{.Price}}</p>
{{slot "stock"}}
</article>
<aside>{{slot "similar"}}</aside>
When a request for /products/42 comes in:
- The product's handler runs.
- Once it returns, the stock and similar handlers start together, and the product's template starts writing.
- The template reaches
{{slot "stock"}}and waits for the stock box; then{{slot "similar"}}, whose handler has usually finished by then.
ctx on, so it gives up when the 300 millisecond timeout cancels that context, and the stock box, with no failure policy, renders nothing. The similar products were fetched at the same time, so the failure cost the page 300 milliseconds and one box, not a 500.What each failure does to this page:
- The stock service is down or slow. The box renders nothing, the page answers 200, and the failure is logged as a warning. In development an HTML comment marks where the box would have been.
- The similar-products call fails.
browse-cataloguerenders in their place, and the page answers 200. - There is no product 42. The error wraps
collage.ErrNotFoundon a required fragment, so the reader gets the not-found page with a 404. - The catalogue itself fails. The product is required, so the page's error page is served with a 500.
A page served without its stock box is degraded, so it is never cached: had the page declared Incremental(ttl), the next request would still ask the stock service again rather than keep the page without the box for a TTL. With no strategy declared, the handlers make it dynamic — see Caching.
Slots filled per render
Everything above binds children when the program starts. Some pages are arranged by their content instead: a landing page whose sections an editor picks and orders in a CMS, a dashboard of widgets a user chose.
Binding those at startup would mean a restart for every change, and code that has to agree with the data about what goes where.
WithSlotResolver fills a slot per render. The resolver receives the render's context and its RenderContext, and returns the fragments the slot holds this time:
type block struct {
Kind string
Heading string
Text string
}
var blocksKey = collage.NewKey[[]block]("blocks")
landing := collage.NewFragment("landing", "pages/landing.html").
WithData(collage.Effect(func(ctx context.Context, rc *collage.RenderContext) error {
blocks, err := cms.Blocks(ctx, "landing")
if err != nil {
return err
}
blocksKey.Set(rc, blocks)
return nil
})).
WithSlot("blocks", collage.SlotRequired).
WithSlotResolver("blocks", func(ctx context.Context, rc *collage.RenderContext) ([]*collage.Fragment, error) {
blocks, _ := blocksKey.Get(rc)
fragments := make([]*collage.Fragment, 0, len(blocks))
for i, b := range blocks {
f, err := blockFragment(i, b)
if err != nil {
return nil, err
}
fragments = append(fragments, f)
}
return fragments, nil
}).
Required().
Build()
A resolver may return fragments that exist for the whole program, or build them on the spot. Building them is how each block gets its own data:
func blockFragment(i int, b block) (*collage.Fragment, error) {
switch b.Kind {
case "hero", "text":
return collage.NewFragment(fmt.Sprintf("block-%d-%s", i, b.Kind), "blocks/"+b.Kind+".html").
WithData(collage.Value(b)).
Build(), nil
}
return nil, fmt.Errorf("landing: unknown block kind %q", b.Kind)
}
The rules:
- The resolver runs after its own fragment's data handler, so it can read what that handler fetched, and before the fragments it returns start theirs — which then run concurrently, like any other children.
- What it returns is held to the slot's rules: at most one fragment unless the slot allows multiple, at least one if it is required (
ErrRequiredSlotEmpty). An error from the resolver, or a panic, fails its fragment, and that fragment's failure policy applies. - A slot bound only to a resolver is optional and holds any number.
WithSlot, before or after it, makes it required or single, asblocksabove is required. A slot is filled by a resolver or byWithSlotFragment, never both — mixing them recordsErrSlotResolved. - A resolver makes the page dynamic unless it declares a strategy, as a data handler does: what it returns may depend on the request.
- Its fragments are only checked when they render. Registration cannot see them, so a returned fragment whose template does not exist fails that render rather than startup. A mistake its builder recorded is caught the same way: a returned fragment built with errors fails the fragment that owns the slot, under that fragment's failure policy, with the returned fragment's name in the error. Check
BuildErr()yourself when you would rather handle it in the resolver. Nor are their templates checked against their data's type, or escaped ahead of the render, which registration does for every other fragment. Templates are all loaded at startup, so the set of block kinds a resolver can use is still fixed by the program.
A page whose sections come from content should also report that content's tags — here the landing handler could be written with collage.LoadTagged rather than with collage.Effect, returning "landing" as a tag — so a cached page is dropped when an editor reorders it. See Caching.
The nesting limit
A fragment tree may be at most 32 levels deep, counting the root. A page that goes deeper fails to render with ErrMaxDepthExceeded, whatever its fragments' failure policies, and the error names the chain of fragments that reached the limit.
Real pages come nowhere near it. The limit exists for the one case registration cannot rule out: a resolver that returns a fragment which, somewhere below, resolves to itself again. A bound cycle is already refused at registration as ErrFragmentCycle.
Fragments with their own URL
A fragment can also be fetched without the page around it — search results refreshed by a fetch(), a panel swapped in after a form posts. That is declared on the page, with WithFragmentPath(locale, pattern, fragment), and nothing is reachable that way unless it is declared. Such a fragment is checked with the page at registration — its template, its builder's mistakes, its validation. See Forms and actions.