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()
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:
| Called | Error |
|---|---|
| with no layouts | ErrMissingLayout |
| with a nil layout | ErrNilFragment |
| with the same layout twice | ErrFragmentCycle |
| a second time on one builder | ErrConflictingLayout |
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
Cachedare added to every page that rendered the layout, soapp.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
WithTimeoutand aWithFallback, 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.
It answers in one of three ways:
| Return | What the reader gets |
|---|---|
nil, nil | The page |
a 3xx status and a Location | A 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 location | That 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,
GETandHEAD. 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 beStatic(). 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
WithFragmentPathis 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:
| Segment | Matches |
|---|---|
blog | Exactly that text |
{slug} | Exactly one segment, captured as slug |
{slug}.md, post-{id}, v{version}.json | One 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:
| Example | Result | |
|---|---|---|
| Disjoint: no segment matches both | {slug}.md and {slug}.json | Both 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 specific | a{x} and {x}b, both matching aXb | ErrOverlappingPattern, 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 —ErrInvalidPathorErrInvalidPattern. - A segment holds at most one placeholder, and a catch-all takes no text around it:
/{name}.{ext}and/files/{path...}.mdareErrInvalidPattern. - A pattern uses each placeholder name once:
/a/{id}/b/{id}has no way to say whichida link fills —ErrInvalidPattern. - A path whose first segment is a locale's code, in any case, such as
/tr/guideor/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}.mdand{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 secondnext; - a destination that would leave the site,
//hostor/\host, isErrInvalidPathat registration; - a control character in either path, such as a line feed, is
ErrInvalidRedirect; - a destination its own source matches is a loop,
ErrRedirectLoop:/docsto/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:
| Method | Strategy | Behaviour |
|---|---|---|
Dynamic() | StrategyDynamic | Rendered on every request, never cached |
Static() | StrategyStatic | Rendered once, served from cache until its tags are invalidated |
Incremental(ttl) | StrategyIncremental | Served 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 wrappingcollage.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
WithNotFoundPageorWithErrorPagemust be registered, withRegisterPage,RegisterNotFoundPageorRegisterErrorPage. Otherwise the application refuses to start withErrUnregisteredErrorPage— 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:
- refuses a nil page, an empty name, a name another page holds (
ErrDuplicatePage), and any registration after the application has started (ErrAppStarted); - refuses a page whose builder, or the builder of any fragment reachable from it or opened with
WithFragmentPath, recorded a mistake — whatBuildErr()would have returned; - copies the slot table of every layout in the chain, binds the content fragment into the innermost one's
contentslot and each layout into the next outer one's; - 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;
- checks that every fragment's template was loaded (
ErrTemplateNotFound) — including the fragments opened withWithFragmentPathand the page's own not-found and error pages — thathtml/templatecan 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; - resolves the strategy of a page that declared none, from the whole tree;
- 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.Pagethat was registered. A page of the same name built separately is refused withErrUnregisteredErrorPage, 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 withErrUnregisteredPagerather than rendered empty. An action on the page's own URL has it asrc.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.Pageis 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 acollage.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:
| Page | Path | Layouts, outermost first | Strategy |
|---|---|---|---|
post | /blog/{slug} | Master | Incremental(10 * time.Minute) |
account | /account | Master, Account | none declared: dynamic, it has a data handler |
admin-users | /admin/users | Master, Account, Admin | none declared: dynamic, it has a data handler |
not-found, error | no path | Master | Dynamic() |
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:
| Request | Reader | Answer |
|---|---|---|
/blog/hello | signed out | The post; with caching on, from the cache until ten minutes have passed |
/blog/hello | signed in | The post, rendered fresh: the session plugin skips the cache for a reader with a session |
/blog/no-such-post | anyone | 404 and the site's not-found page, in the shell |
/account | signed out | 303 to /login?next=%2Faccount |
/admin/users | signed out | 303 to /login?next=%2Fadmin%2Fusers: the account guard answers first, and the role is never checked |
/admin/users | signed in, not an admin | 403, with no body |
/admin/users | an admin | The page |
A few things follow from the rules above:
- No list of private paths. A new page under
/adminis private because it listslayouts.Admin(), not because of where its path starts. A page that forgets it is public, socollage inspectis 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, the303and403withno-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.