Core concepts27 min read

Pages and layouts

What a page is: its layouts and content, who may see it, the paths that reach it, how it is cached, what it shows when it fails, and what registration does.

A page is a render configuration with a name. It says which fragments make up the page — a layout and the content inside it — which URLs reach it, how its output is cached, and which page to show instead when it cannot be rendered. It has no template and no data of its own; those belong to its fragments.

page := collage.NewPage("blog-post").
	WithLayouts(layout).
	WithContent(post).
	WithPath("en", "/blog/{slug}").
	Incremental(10 * time.Minute).
	Build()

if err := app.RegisterPage(page); err != nil {
	log.Fatal(err)
}

Building a page

collage.NewPage(name) starts a builder, each WithX call sets one thing, and Build() returns the *collage.Page.

The name is the page's identity. Links are built from it ({{pageURL "blog-post" "slug" .Slug}}), tests and plugins look pages up by it, and two pages cannot share one. Choose it for what the page is, not where it lives, so that it survives the URL changing.

The builders never stop a chain to return an error. A call that cannot do what it was asked records the error and carries on, and BuildErr() returns everything recorded:

builder := collage.NewPage("blog-post").WithLayouts(layout).WithPath("en", "/blog/{slug}")
page := builder.Build()
if err := builder.BuildErr(); err != nil {
	return err // collage.ErrMissingContent: there is no WithContent
}

Ignoring BuildErr does not let a mistake through. What a builder recorded stays on the value it built, and RegisterPage refuses a page carrying any — its own, or those of any fragment in its tree, such as a slot declared twice — with an error naming the page, whether or not anyone called BuildErr. Check BuildErr when a page is built from input you do not control, where you want the error closer to its cause.

Layout and content

Most pages on a site share their outside — the <head>, the header, the footer — and differ inside. The outside is the layout, a fragment whose template calls a slot named content. The inside is the content fragment, the one the page exists to show.

layout := collage.NewFragment("layout", "layouts/master.html").
	WithTitle("My site").
	Build()
<!-- templates/layouts/master.html -->
<!doctype html>
<html lang="en">
<head>{{hoist "head"}}</head>
<body>
  <header>…</header>
  {{slot "content"}}
  <footer>…</footer>
</body>
</html>

The layout declares no slot. The {{slot "content"}} in its template is the declaration, and so is any other slot it calls — see Fragments and slots. WithTitle gives every page that uses it a <title> until something inside names a better one.

WithLayouts(layout) and WithContent(post) name the two, and registration puts the content into the layout's content slot (collage.DefaultContentSlot). You do not bind it yourself, and a layout whose template never calls {{slot "content"}} is refused at registration with ErrUnknownSlot, because the content would have nowhere to render. WithSlot(collage.DefaultContentSlot, collage.SlotRequired, collage.SlotSingle) on the layout is still accepted, for a layout that should refuse any fragment bound into content besides the page's own (ErrSlotOccupied).

A page must have content — ErrMissingContent otherwise. The layout is optional: a page without one renders its content fragment as the whole response, which is what a page whose template is a complete HTML document wants.

One layout, many pages

A layout is the most reused thing on a site, so it is safe to share one *collage.Fragment value between every page, error pages included. Registration gives each page a private copy of the layout's slot table before binding the content into it, so page A's content never appears on page B.

Only the slot table is copied. The layout's template, its data handler, its fallback and the fragments already bound into its other slots stay shared — which means registration takes a snapshot of those bindings. A fragment bound into the shared layout after a page was registered does not appear on that page. Build the layout completely, then register pages with it.

The scaffold writes its layout as a function, layouts.Master(), which returns a new fragment each call. That works just as well; sharing one value is simply allowed.

Layouts inside layouts

A page can sit in more than one layout: the HTML shell with its <head>, and inside it a narrower frame the sign-in pages share. WithLayouts takes the whole chain, outermost first; a single layout is WithLayouts(layout):

func Master() *collage.Fragment {
	return collage.NewFragment("layout", "layouts/master.html").
		WithTitle("My site").
		Build()
}

func Auth() *collage.Fragment {
	return collage.NewFragment("auth-layout", "layouts/auth.html").Build()
}

page := collage.NewPage("login").
	WithLayouts(layouts.Master(), layouts.Auth()).
	WithContent(login).
	WithPath("en", "/login").
	Build()
The login page's layout chain after registration. The outermost layout, Master, has a content slot holding the auth layout, the second and innermost layout. The auth layout's content slot holds the login content fragment.Master()1st · outermostslot "content"Auth()2nd · innermostslot "content"login · content
WithLayouts(layouts.Master(), layouts.Auth()) lists the chain outermost first. Registration does the nesting: the login content goes into the content slot of Auth(), the innermost layout, and Auth() into the content slot of Master(), each on the page's own copy of the layout's slot table.

Every layout in the chain renders the one inside it with {{slot "content"}}, as a single layout renders the content. Registration does all of the wrapping: the content goes into the innermost layout's content slot, and each layout into the content slot of the one outside it.

So a layout with a hole in it is still a finished *collage.Fragment, and a helper that makes one returns it built, not as a builder the page has to complete.

Each page gets its own copy of every layout's slot table, as it does of a single layout, so the chain's layouts can be shared across the site. A layout in a chain must arrive with its content slot empty — registration fills it — and is refused with ErrSlotOccupied otherwise.

WithLayouts records an error, which registration refuses, when it is called:

CalledError
with no layoutsErrMissingLayout
with a nil layoutErrNilFragment
with the same layout twiceErrFragmentCycle
a second time on one builderErrConflictingLayout

A layout with data of its own

A layout is a fragment, so the parts of it that come from a CMS — the site's name, a menu, the footer's links — are loaded the way a page's content is: with WithData. Give each part a fragment of its own, bound into a slot of the layout, so each loads only what it shows and fails alone:

var menuKey = collage.NewKey[[]backend.MenuItem]("menu")

func Master(api *backend.API) *collage.Fragment {
	return collage.NewFragment("layout", "layouts/master.html").
		WithData(collage.Load(headData(api))). // title, meta tags: hoisted into the head
		WithSlotFragment("header", Header(api)).
		WithSlotFragment("footer", Footer(api)).
		Build()
}

func Footer(api *backend.API) *collage.Fragment {
	return collage.NewFragment("footer", "layouts/footer.html").
		WithData(collage.Load(func(ctx context.Context, rc *collage.RenderContext) (footerView, error) {
			menu, err := collage.Cached(rc, menuKey, time.Hour, []string{"menu"}, api.Menu)
			return footerView{Menu: menu}, err
		})).
		Build()
}
<!-- templates/layouts/master.html -->
<body>
  {{slot "header"}}
  {{slot "content"}}
  {{slot "footer"}}
</body>

The client the data comes from is passed to the layout's constructor, as to any page's, from where routes.go builds them. Three things follow from the layout being part of every page:

  • Fetch it once, not once per page. Every page renders the menu, so read it through collage.Cached: thirty pages then fetch it once, and a static export does too.
  • The tags make a change reach every page. The tags given to Cached are added to every page that rendered the layout, so app.InvalidateTags(ctx, "menu") — from the CMS's webhook — refreshes the menu and drops every cached page that showed it.
  • A slow CMS slows every page. Give the part a WithTimeout and a WithFallback, so a menu that does not arrive is a page without a menu rather than a page that does not arrive; see When a fragment fails.

Private pages: guards

A section of a site that only signed-in readers may see is a layout that says so. WithGuard gives a fragment a function that is asked, before the page is served, whether this request may have it:

func requireUser(ctx context.Context, r *http.Request) (*collage.GuardDecision, error) {
	if session.FromContext(ctx).Get("user") != "" {
		return nil, nil // allowed
	}
	login, err := collage.URL(ctx, "login", nil)
	if err != nil {
		return nil, err
	}
	return &collage.GuardDecision{
		Status:   http.StatusSeeOther,
		Location: login + "?next=" + url.QueryEscape(r.URL.RequestURI()),
	}, nil
}

func Private() *collage.Fragment {
	return collage.NewFragment("private", "layouts/private.html").
		WithGuard(requireUser).
		Build()
}

page := collage.NewPage("dashboard").
	WithLayouts(layouts.Master(), layouts.Private()).
	WithContent(dashboard).
	WithPath("en", "/dashboard").
	Build()

A guard sends the reader to a page by its name, not a path written into it. collage.URL(ctx, name, params) is rc.URL for code that has no render: it builds in the locale the request is in, so a guard on /tr/dashboard sends the reader to the Turkish login, and falls back to the default locale as {{pageURL}} does. Without a query to add, collage.GuardSeeOtherPage(ctx, "login", nil) returns the whole decision — a guard's SeeOtherPage, which returns an action's *ActionResult instead. An unknown name is an error and fails the request; it lets nobody through.

collage add guard private writes the guard, refusing everyone until you write its check; collage add layout private --guard private writes a layout that carries it, and collage add page dashboard --guard private puts it on a new page's content (see collage add).

Every page wrapped in Private() is private, and a page is public by leaving it out. There is no list of protected paths to keep in step with the routes: the guard runs for whatever URL reaches the page, in every locale, with every parameter.

The parameters are on the request: r.PathValue("slug") is the {slug} of the page's pattern, whichever locale's path the request came in on. A guard that lets only a post's author edit it reads the slug and answers 404 to anyone else, so a slug tells nothing about posts that are not theirs:

func Author(posts *blog.Posts) collage.GuardFunc {
	return func(ctx context.Context, r *http.Request) (*collage.GuardDecision, error) {
		post, ok := posts.BySlug(r.PathValue("slug"))
		if !ok || post.AuthorID != session.FromContext(ctx).Get(session.UserKey) {
			return &collage.GuardDecision{Status: http.StatusNotFound}, nil
		}
		return nil, nil
	}
}

A guard is asked for a page when it is on the page's spine: a layout in the page's chain, or the page's content fragment. Guards run outermost first, the content fragment's last, and the first that answers decides.

A guard on any other fragment — one bound into a slot, one a resolver returns, a fallback — is ignored: who may see a page is a property of the page, not of the parts it is drawn from.

A request for /admin/users meets the guards on the page's spine, outermost first. Master has no guard. Account's guard answers a signed-out reader with 303 to /login. Admin's guard answers a reader who is not an admin with 403 and no body. The content fragment, admin-users, is asked last. Only when no guard answers does the page render; for a cached page, the cache is read only after the guards too. A menu fragment bound into a slot is not on the spine, so a guard on it is not asked.GET /admin/usersMasterlayout 1 · no guardAccountlayout 2 · RequireUsersigned out303 · /loginAdminlayout 3 · requireRolenot an admin403 · no bodyadmin-userscontent · asked lastmenu · in a slotguard not askedpage rendersoutermost first · the first answer decides
The spine of the admin page in Example: a blog with a private area. A request meets the guards of its layouts, outermost first, then the content fragment's. The first guard that answers sends its answer and nothing further runs: a signed-out reader gets a redirect to log in from the account layout, a signed-in reader who is not an admin gets a bare 403 from the admin layout. Only a request no guard answered reaches the render, and on a cached page the cache, which is read only after the guards. A guard on a fragment bound into a slot, such as the admin menu, is not asked.

It answers in one of three ways:

ReturnWhat the reader gets
nil, nilThe page
a 3xx status and a LocationA redirect there, with no body. A zero status with a location is 303 See Other. A request marked with Collage-Fetch gets 204 and the destination in Collage-Location, as an action's redirect does.
a 4xx or 5xx status, no locationThat status, with no body

Anything else — a redirect with nowhere to go, a 200 — is ErrInvalidGuardDecision, and the request fails with a 500, as it does when the guard returns an error. A guard that cannot say what it means is not guessed about: a redirect with no location would otherwise fall through to the very page it was meant to keep back.

What the guard covers:

  • The page's renders, GET and HEAD. The guard runs after routing and before the page's cache is read, so a blocked reader never reaches a cached render, and a private page may be Static(). It also runs before any render hook: a blocked request never reached the page, so plugins watching renders are not told about it.
  • The actions on the page's own URL. A form posts to the page it sits on, and a page a reader may not see is a page whose form they may not submit. The guard runs before the body is read and before the forgery check.
  • The page's fragment paths. A fragment opened at its own URL with WithFragmentPath is a part of the page, and meets the page's guards before the fragment's own, so a fragment path on a private page is private too.
  • Not an action registered at its own URL, and not the page's not-found and error pages — a private error page would otherwise redirect the reader who hit the error.

Readers the guard allows share the page's cache, which is the server's own — unless something skips it for them, as elagoht/session does for every reader with a session. A CDN or proxy in front of the server runs no guard, so a guarded page goes out with Cache-Control: private, no-cache whatever its strategy says.

The guard's own answer — a redirect to log in, a refusal — is sent no-store, so a CDN that keeps a 404 or a 308 by default does not hand one reader's answer to the next.

A page whose content differs from one reader to the next is a personalisation question, not a guard question — see Caching. A static export does not write guarded pages at all.

What a guard checks is not the framework's to know. requireUser above reads the session; a guard can as well read a header, a role, a feature flag — anything a request carries. The session plugin ships this one ready-made, as session.RequireUserPage("login") — or session.RequireUser("/login") with the path written. collage inspect lists, for each page, the fragments that carry a guard.

Paths

WithPath(locale, pattern) registers the URL that reaches the page in one locale. A site with one language uses one locale, and a page may have a different path in each:

collage.NewPage("about").
	WithContent(about).
	WithPath("en", "/about").
	WithPath("tr", "/hakkinda")

A pattern is made of segments:

SegmentMatches
blogExactly that text
{slug}Exactly one segment, captured as slug
{slug}.md, post-{id}, v{version}.jsonOne segment carrying that text before and after, with at least one character between, which is what is captured: /blog/hello.md gives slug = hello
{rest...}Everything that is left, captured as rest. Only as the last segment, with no text around it

A data handler reads what was captured with rc.Param("slug"), or rc.PathParams["slug"]. Values arrive percent-decoded, one segment at a time.

A segment holding an encoded slash, %2F, is a 404. By the URL standard %2F is not a separator: /public%2Fsecret is one segment whose value is public/secret.

But Go decodes the path into r.URL.Path before any middleware reads it, and there /public%2Fsecret has become /public/secret, which no longer tells an encoded slash from a real one. So a middleware sees two segments where the router sees one. A router that matched the one would serve a request the middleware had judged as something else, so collage serves neither reading.

A segment that decodes to bytes that are not UTF-8, such as %c3%28, is a 404 too: {{pageURL}} and App.URL escape Go strings as UTF-8, so no link of the site's holds one.

A value that is itself a path, such as guide/intro, belongs in a catch-all: {rest...}. {{pageURL}} and BuildPath refuse a / in a single segment's value.

At every level a static segment is tried first, then a placeholder with text around it — the most specific first — then a bare {param}, then a {rest...}, with backtracking, so /blog/archive beats /blog/{slug} even when both could match.

/blog and /blog/ are the same route, with one address: a page's other spelling is a 301 to it, with the query kept. The address is the one without the slash, or the one with it under Config.TrailingSlash. A document and an action are spelled without the slash in both modes, as their links are built: /sitemap.xml/ is a 301 to /sitemap.xml, and a POST to /login/ a 308 to /login, so the form is posted again. A middleware still sees the path as it arrived, before the router redirects, so one that guards an exact path should compare it without the trailing slash.

Text around a placeholder

A post and its Markdown, or a feed per category, sit side by side:

collage.NewPage("post").WithPath("en", "/blog/{slug}")            // /blog/hello
collage.NewDocument("post-md", "text/markdown; charset=utf-8").
	WithPath("en", "/blog/{slug}.md")                               // /blog/hello.md
collage.NewDocument("feed", "application/rss+xml").
	WithPath("en", "/feeds/{category}.xml")                         // /feeds/go.xml

Which route a segment reaches never depends on the order of registration. Two placeholders at one position are one of three things:

ExampleResult
Disjoint: no segment matches both{slug}.md and {slug}.jsonBoth register; the text decides
Nested: one is the other made more specific{slug}.min.md within {slug}.md, both within {slug}Both register; the more specific wins
Crossing: a segment matches both, neither is more specifica{x} and {x}b, both matching aXbErrOverlappingPattern, naming such a segment

So with the routes above, /blog/hello.md is the document, /blog/hello the page, a static /blog/index.md beats both, and /blog/.md — nothing between the text — is the page's, with slug = .md. A placeholder with text around it never captures . or ..: /blog/...md is the page's too, rather than handing the document the slug ... A link escapes only the value: {{pageURL "post-md" "slug" "çay"}} is /blog/%C3%A7ay.md, and an export writes blog/hello.md beside blog/hello/index.html.

A segment holds one placeholder — {name}.{ext} has no single answer for a.b.c, so register {name}.md and {name}.json as two routes — and there is no regex. A value is checked by its handler, which returns collage.ErrNotFound for one it does not know; that keeps every collision decidable when the route is registered.

Mistakes in patterns are errors at registration, not surprises at request time:

  • A pattern must start with /, have no empty segment and no empty placeholder name, and put a catch-all only last — ErrInvalidPath or ErrInvalidPattern.
  • A segment holds at most one placeholder, and a catch-all takes no text around it: /{name}.{ext} and /files/{path...}.md are ErrInvalidPattern.
  • A pattern uses each placeholder name once: /a/{id}/b/{id} has no way to say which id a link fills — ErrInvalidPattern.
  • A path whose first segment is a locale's code, in any case, such as /tr/guide or /EN/about, would be taken for the locale prefix and never reached — ErrLocaleUnreachable. Register the path without it; the prefix is added for you. A placeholder as the first segment is fine. The same holds for a document's, an action's and a redirect's source.
  • Two placeholders with text around them that cross, such as /a{x} and /{x}b — ErrOverlappingPattern.
  • Two routes at one path in one locale — ErrDuplicateRoute. That includes a page and a document colliding, since they share one tree.
  • Two parameter names at one position, such as /blog/{slug} and /blog/{id}/edit, or {slug}.md and {id}.md — ErrAmbiguousParameterName.

A page answers GET and HEAD, and OPTIONS with a 204 whose Allow header lists what the URL accepts. Any other method is a 405 with that same Allow header, unless the page has an action for it — which is how a form posts to the page it sits on.

Locales, locale prefixes such as /tr/hakkinda — and the redirect that sends /en/about to /about — and building links from page names are covered in Links and locales.

A page can also carry redirects from old URLs, with WithRedirect(from, to, status) and WithPermanentRedirect(from, to):

  • a redirect carries the request's query string to its destination;
  • a value it captured is escaped for where it lands — a path segment, or a query value after a ?, so /login?next={slug} cannot be handed a second next;
  • a destination that would leave the site, //host or /\host, is ErrInvalidPath at registration;
  • a control character in either path, such as a line feed, is ErrInvalidRedirect;
  • a destination its own source matches is a loop, ErrRedirectLoop: /docs to /docs/, since a source matches with or without its slash, or /blog/{slug} to /blog/{slug};
  • a source that matches a page's or a document's path is ErrRedirectShadowsPage, in either order of registration, because redirects are matched first and the route would never answer. That includes a source that only matches the path: WithRedirect("/{slug}", "/blog/{slug}", 301) takes /about.txt, so a document there is refused. Narrow the redirect's source. Two patterns that both hold placeholders are not compared, since whether they overlap depends on the request; there the redirect wins.

A static export fails on a redirect over a page it wrote; see Static export.

Render strategies

Every page has one of three strategies, which decide whether its output is cached:

MethodStrategyBehaviour
Dynamic()StrategyDynamicRendered on every request, never cached
Static()StrategyStaticRendered once, served from cache until its tags are invalidated
Incremental(ttl)StrategyIncrementalServed from cache, rendered again once ttl has passed

A page that calls none of the three is StrategyAuto until it is registered, and registration resolves it: dynamic if anything it renders has a data handler or a slot resolver, static otherwise. A page of templates and fixed values — collage.Value, WithTitle — renders the same for everyone, so it is cached without saying so. A handler may read the request, a cookie or the clock, and nothing outside it can tell, so a page with one renders per request until it says Static() or Incremental(ttl). Caching has the whole rule.

Incremental needs a positive TTL (ErrInvalidTTL). Static and incremental pages are also the ones collage export can write to files; a dynamic page is skipped, because it exists to render per request.

Caching only happens when the application enables it (Config.Cache.Enabled, on in the scaffold), and never in development, where a cached page would hide the template you just edited.

A cached page is sent Cache-Control: public only when nothing in the response is one reader's: a response a middleware has already given a Set-Cookie goes out private, no-store, so a CDN cannot hand that cookie to the next reader, and it is still cached on the server. A request over TLS and a plain one for the same URL are separate entries in the cache key.

Two more builder methods shape a cached page. WithDependencyTags(tags...) adds dependency tags of the page's own to those its data handlers report, and WithCacheParams(names...) says which query parameters take part in the cache key. How all of this fits together — tags, invalidation, query parameters, caching data rather than pages — is in Caching.

Not-found and error pages

When a page cannot be shown, another page is shown in its place. There are two situations and two levels.

  • Not found — 404. No route matched the URL, or a Required() fragment's data handler returned an error wrapping collage.ErrNotFound: the content the URL names does not exist.
  • Error — 500. A Required() fragment failed any other way, or something in the framework's own path did.

A page can name its own replacement pages, and the application can name site-wide ones:

post := collage.NewPage("blog-post").
	WithLayouts(layout).
	WithContent(postContent).
	WithPath("en", "/blog/{slug}").
	WithNotFoundPage(postNotFound). // "no such post", with a search box
	WithErrorPage(postError).
	Build()

app.RegisterNotFoundPage(siteNotFound)
app.RegisterErrorPage(siteError)

For a failure, the page's own NotFoundPage or ErrorPage is used first, then the site-wide one, then the framework's built-in page. A URL that matched no route has no page to ask, so it goes straight to the site-wide not-found page.

An error page is a page like any other — a layout, a content fragment, data handlers if it wants them — with no path. It does not need one; it is reached by something failing.

func NotFoundPage() *collage.Page {
	content := collage.NewFragment("not-found-content", "pages/404.html").Build()

	return collage.NewPage("not-found").
		WithLayouts(layouts.Master()).
		WithContent(content).
		Dynamic().
		Build()
}

A few rules keep error pages from failing at the worst moment:

  • Every page named in WithNotFoundPage or WithErrorPage must be registered, with RegisterPage, RegisterNotFoundPage or RegisterErrorPage. Otherwise the application refuses to start with ErrUnregisteredErrorPage — see below for why.
  • Their templates are checked when the page that names them is registered, so a typo in a 500 page is a startup error, not something discovered while the site is already failing.
  • A page cannot be its own error page (ErrSelfErrorPage).
  • An error page's render is never cached, and if it fails or renders nothing, the built-in page is served instead, and the failure is logged and reported to plugins. A 500 page that can 500 into itself is an outage.

The built-in page is self-contained HTML with no external files, so it renders even when the assets are what broke. In development it names the fragment where the failure started and shows the error chain; in production one generic sentence, because error text leaks hostnames, file paths and credentials. Errors lists every error the framework reports.

collage export writes the page registered with RegisterNotFoundPage as 404.html, which is the file static hosts serve for a missing URL.

Registration

if err := app.RegisterPage(page); err != nil {
	log.Fatal(err)
}

RegisterPage is where a page is checked and put together, so that what would fail at render time fails here, at startup, with the page's name in the message — for every fragment the page holds, including one it opens at its own URL. A fragment a slot resolver returns while a request runs cannot be seen from here; it is checked when it first renders. In order, it:

  1. refuses a nil page, an empty name, a name another page holds (ErrDuplicatePage), and any registration after the application has started (ErrAppStarted);
  2. refuses a page whose builder, or the builder of any fragment reachable from it or opened with WithFragmentPath, recorded a mistake — what BuildErr() would have returned;
  3. copies the slot table of every layout in the chain, binds the content fragment into the innermost one's content slot and each layout into the next outer one's;
  4. validates the page and its whole fragment tree, fragment paths included: paths, strategy and TTL, redirects, required slots with nothing in them, a fragment reachable from itself;
  5. checks that every fragment's template was loaded (ErrTemplateNotFound) — including the fragments opened with WithFragmentPath and the page's own not-found and error pages — that html/template can escape it, and that every slot something is bound into is one its template calls (ErrUnknownSlot, naming the slot and the calls the template does make). A template the escaper refuses — a <script> string that never closes, {{if}} branches that leave an attribute in different states — would otherwise pass startup and fail on its first request, so it is an error here naming the fragment;
  6. resolves the strategy of a page that declared none, from the whole tree;
  7. adds the page's paths, redirects, actions and fragment paths to the router, which refuses one that collides with what is already there: a duplicate route, an ambiguous parameter name, a redirect over a route.

Treat any error as fatal. A registration that fails halfway is not rolled back — a path accepted in one locale stays in the router when the next is refused — because a failed registration is a program that should not start, not a condition to recover from.

Registering several at once

app.Register takes pages, documents and actions in one call and registers each in order, through RegisterPage, RegisterDocument or RegisterAction. The scaffolded routes.go is a single call to it:

func register(app *collage.App) error {
	if err := app.Register(
		pages.Home(),
		blogpages.Post(),
		documents.Health(),
		authactions.Logout(),
	); err != nil {
		return err
	}
	return app.RegisterNotFoundPage(errorspages.NotFound())
}

It stops at the first one refused and returns its error wrapped with its kind and name — register page "post": collage: duplicate page ... — so errors.Is still finds the cause. What was registered before it stays registered, as with the single methods. A nil is ErrNilRegistrable. The not-found and error pages are reached by failing to match, not by a path, so they keep RegisterNotFoundPage and RegisterErrorPage. Register takes a collage.Registrable, which only *Page, *Document and *Action satisfy. collage add adds what it writes to this call.

Why the registered value matters

Registration changes the page it is given. Step 3 replaces the page's outermost layout with a private, bound copy of it, and that copy — with the rest of the chain and the content inside it — is what renders. A page built again by calling the same constructor is a different value, whose layouts have empty content slots. So is a second Build() on the same builder: each call returns an independent copy, and WithPath on the builder afterwards reaches neither. Build once and keep the *Page.

So the value you passed to RegisterPage is the page from then on, and everything that refers to a page by value must use that one:

  • Error pages.WithNotFoundPage(p) must point at the very *collage.Page that was registered. A page of the same name built separately is refused with ErrUnregisteredErrorPage, because it would render its layout around nothing.

  • Actions that answer with a page.collage.RenderPage(p) in an action must be given the registered value; an unregistered one is refused with ErrUnregisteredPage rather than rendered empty. An action on the page's own URL has it as rc.Page:

    return collage.NewPage("hello").
    	WithLayouts(layouts.Master()).
    	WithContent(content).
    	WithPath("en", "/hello").
    	WithAction("POST", func(_ context.Context, rc *collage.RenderContext) (*collage.ActionResult, error) {
    		return collage.RenderPage(rc.Page), nil
    	}).
    	Build()
    
  • rc.Page is that value too, shared by every request that renders the page and every goroutine serving them. Read it freely; never write to it. Anything that varies per request belongs in the data a handler returns or under a collage.Key — see Data handlers.

app.Page(name) and app.Pages() return copies of registered pages, for looking at them — a sitemap listing every page's paths, a test checking a strategy. A copy is not the registered value, so do not pass one where a registered page is expected.

Example: a blog with a private area

A multi-user blog has three kinds of page. Posts are public. Each signed-in writer has an account page listing their drafts. Admins also have a page listing the users. The three share one shell, and the private ones sit in layouts that say who may enter:

PagePathLayouts, outermost firstStrategy
post/blog/{slug}MasterIncremental(10 * time.Minute)
account/accountMaster, Accountnone declared: dynamic, it has a data handler
admin-users/admin/usersMaster, Account, Adminnone declared: dynamic, it has a data handler
not-found, errorno pathMasterDynamic()

The layouts carry the guards. Account uses the session plugin's RequireUserPage, which sends a signed-out reader to the page named login with where they were going in next. Admin checks a role, under a session key "role" that this application's own login action writes; the plugin defines only the user key.

// Master is the site's shell: <head>, header, footer.
func Master() *collage.Fragment {
	return collage.NewFragment("layout", "layouts/master.html").
		WithTitle("My blog").
		Build()
}

// Account is the signed-in area. Its guard sends everyone else to log in.
func Account() *collage.Fragment {
	return collage.NewFragment("account-layout", "layouts/account.html").
		WithGuard(session.RequireUserPage("login")).
		Build()
}

// Admin sits inside Account and lets only admins through.
func Admin() *collage.Fragment {
	menu := collage.NewFragment("admin-menu", "fragments/admin-menu.html").Build()

	return collage.NewFragment("admin-layout", "layouts/admin.html").
		WithGuard(requireRole("admin")).
		WithSlotFragment("menu", menu).
		Build()
}

// requireRole lets through a reader whose session holds role under "role",
// which the login action sets. Anyone else gets a bare 403.
func requireRole(role string) collage.GuardFunc {
	return func(ctx context.Context, _ *http.Request) (*collage.GuardDecision, error) {
		if session.FromContext(ctx).Get("role") == role {
			return nil, nil
		}
		return &collage.GuardDecision{Status: http.StatusForbidden}, nil
	}
}

The admin layout calls both of its slots: menu, bound above, and content, which registration fills. layouts/account.html is the same with only content.

<!-- templates/layouts/admin.html -->
<div class="admin">
  <nav>{{slot "menu"}}</nav>
  <main>{{slot "content"}}</main>
</div>

A page is public or private by the layouts it lists, and nothing else:

// Post is public and cached; an unknown slug is a 404.
func Post() *collage.Page {
	content := collage.NewFragment("post", "pages/post.html").
		WithData(collage.LoadTagged(func(ctx context.Context, rc *collage.RenderContext) (store.Post, []string, error) {
			slug := rc.Param("slug")
			// PostBySlug wraps collage.ErrNotFound for a slug it does not know.
			post, err := store.PostBySlug(ctx, slug)
			return post, []string{"post:" + slug}, err
		})).
		Required().
		Build()

	return collage.NewPage("post").
		WithLayouts(layouts.Master()).
		WithContent(content).
		WithPath("en", "/blog/{slug}").
		Incremental(10 * time.Minute).
		Build()
}

// Account lists the signed-in reader's drafts.
func Account() *collage.Page {
	content := collage.NewFragment("account", "pages/account.html").
		WithData(collage.Load(func(ctx context.Context, rc *collage.RenderContext) ([]store.Draft, error) {
			return store.Drafts(ctx, session.Get(rc).Get(session.UserKey))
		})).
		Build()

	return collage.NewPage("account").
		WithLayouts(layouts.Master(), layouts.Account()).
		WithContent(content).
		WithPath("en", "/account").
		Build()
}

// AdminUsers is for admins only: it sits in both guarded layouts.
func AdminUsers() *collage.Page {
	content := collage.NewFragment("admin-users", "pages/admin-users.html").
		WithData(collage.Load(func(ctx context.Context, _ *collage.RenderContext) ([]store.User, error) {
			return store.Users(ctx)
		})).
		Build()

	return collage.NewPage("admin-users").
		WithLayouts(layouts.Master(), layouts.Account(), layouts.Admin()).
		WithContent(content).
		WithPath("en", "/admin/users").
		Build()
}

// NotFound and Error wrap the shell alone, so they look like the public site.
func NotFound() *collage.Page {
	content := collage.NewFragment("not-found-content", "pages/404.html").Build()

	return collage.NewPage("not-found").
		WithLayouts(layouts.Master()).
		WithContent(content).
		Dynamic().
		Build()
}

func Error() *collage.Page {
	content := collage.NewFragment("error-content", "pages/500.html").Build()

	return collage.NewPage("error").
		WithLayouts(layouts.Master()).
		WithContent(content).
		Dynamic().
		Build()
}
func register(app *collage.App) error {
	if err := app.Register(
		pages.Post(),
		pages.Account(),
		pages.AdminUsers(),
	); err != nil {
		return err
	}
	if err := app.RegisterNotFoundPage(pages.NotFound()); err != nil {
		return err
	}
	return app.RegisterErrorPage(pages.Error())
}

What each reader gets:

RequestReaderAnswer
/blog/hellosigned outThe post; with caching on, from the cache until ten minutes have passed
/blog/hellosigned inThe post, rendered fresh: the session plugin skips the cache for a reader with a session
/blog/no-such-postanyone404 and the site's not-found page, in the shell
/accountsigned out303 to /login?next=%2Faccount
/admin/userssigned out303 to /login?next=%2Fadmin%2Fusers: the account guard answers first, and the role is never checked
/admin/userssigned in, not an admin403, with no body
/admin/usersan adminThe page

A few things follow from the rules above:

  • No list of private paths. A new page under /admin is private because it lists layouts.Admin(), not because of where its path starts. A page that forgets it is public, so collage inspect is worth a look: it lists, per page, the fragments that carry a guard.
  • The admin menu's guard would not be asked. The menu is bound into a slot, not on the spine. Guarding the area is the admin layout's job.
  • Private pages are not shared caches. The account and admin pages go out with Cache-Control: private, no-cache, the 303 and 403 with no-store, and a static export leaves both pages out.
  • The error pages render for anyone. They wrap Master() alone, and the guards of the page that failed are not asked for them, so a reader who hit an error is never redirected to log in instead of seeing it.