Routing: folders, layouts, gates and parameters
The addresses of an app are the folders under pages/: there is no route table. A folder can
capture part of the URL, a page with pages below it is their layout or their gate, and a hook
ends a request with an error page or a redirect by returning an error.
Folders are pages
A folder that holds an index.html is a page at its path:
pages/index.html /
pages/home/index.html /home
pages/users/index.html /users
pages/users/add/index.html /users/add
pages/users/s_login/index.html /users/<login>
pages/users/s_login/info/index.html /users/<login>/info
- A trailing slash is ignored:
/users/is/users. A path with an empty part, such as/users//add, and a path that matches no page answer 404. - Pages take
GET,HEADandPOST. Any other method answers 405.
Parameters
A folder named s_<name> takes any one part of the URL as the string parameter <name>, and a
folder named n_<name> takes only a whole number of digits that fits an int64; a part that is
not one answers 404.
login := r.URLParam("login") // from s_login
id := r.URLParamInt("id") // from n_id, as an int64
- A fixed folder wins over a parameter: with
users/add/andusers/s_login/,/users/addis the add page. A user with the loginaddcould never be opened, so refuse such names. - A folder holds at most one parameter folder (E-GEN-041). A page that needs another one goes
under a fixed folder, such as
notes/n_idandnotes/by-slug/s_slug. - Every hook of every page on the path sees all the parameters of the URL: the layout
pages/users/readsloginto mark the open user in its list. - A page with a parameter shows one record of many, so it says whose records it shows, with
guard="true"orshared="true"on its<ssr:access>or on that of a template between it and its deepest parameter folder (E-GEN-054); see access. URLParamreturns""andURLParamIntreturns 0 for a name the path does not have.
Layouts
A layout has <ssr:content/> where the page below it is shown:
<!-- pages/index.html -->
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><ssr:access role="*"/><title>People</title><ssr:assets/></head>
<body>
<nav>…</nav>
<main><ssr:content default="home"/></main>
</body>
</html>
- Each layout and the page have their own
RouteDataand data provider; they never share variables. Layouts nest:/users/alice/infois the info page inside the user's card, inside the users list, inside the root layout. - Opening a layout itself redirects (302) to its default page.
defaultnames a page below the layout by its folders, relative to the layout, such asdefault="info"inpages/users/s_login/(E-GEN-049). It cannot name a parameter folder, whose value is not known when the pages are generated. - To choose the page when the request comes, leave
defaultout and return the page from the data provider'sDefaultRoute. Its result is joined to the layout's path, and""answers 404:
// DefaultRoute opens the first user.
func (p *DP) DefaultRoute(ctx context.Context, _ *web.Request) (string, error) {
users, err := p.d.Users(ctx)
if err != nil || len(users) == 0 {
return "", err
}
return users[0].Login, nil
}
- In a layout without
default, the stubDefaultRoutethataicoded generatewrites returns"", so opening the layout answers 404 until you write it. - A POST to a layout answers 405: forms belong to the pages shown inside it.
Gates
A page with pages below it and no <ssr:content/> is a gate. Its access rule and Guard apply
to every page below it, but its forms, Data, live values, calls, markup, scripts and styles
stay on its own page, which opening it shows. A list at /notes, with each note at
/notes/42, is a gate with a page below it:
pages/notes/index.html /notes the list; its Guard covers every note
pages/notes/n_id/index.html /notes/42 one note, which writes its own document
A page below a gate is not shown inside it, so it writes its whole document, <!doctype html>,
<html> and a <head> with <ssr:assets/>, unless a layout above the gate does. The root page
follows the same rule: when it is a gate, every page below it writes its whole document.
Errors
A hook ends the request by returning an error:
| Return | Answer |
|---|---|
web.NotFound() |
404 "This page does not exist." |
web.Forbidden() |
403 "You do not have access to this page." |
web.Error(status, message) |
status, from 400 to 599, with message shown to the viewer |
web.Redirect(path) |
303 to path |
| any other error | 500 "Something went wrong.", and the error is logged |
- The error page is the framework's own: a short HTML page with the status and the message, escaped. There is no custom error page.
- Never put internal details in the message of
web.Error. A status outside 400 to 599 is logged as E-WEB-004 and answers 500. - A request without a viewer, which the runner never sends, answers 401 "Sign in through the company login."
Redirects
web.Redirect("/users/" + login) answers 303, so a form that redirects after it succeeds is not
sent again when the viewer reloads. The target must be a path on this site that starts with a
single / (E-WEB-002): a full URL or a path starting with // is refused, logged and answered
with 500, so a page can never send viewers to another site.
Serving the pages
main hands the generated handler to app.Main:
app.Main(app.Options{Handler: pages.NewHandler(d)})
The pages handler answers only requests that come through the app's runner (E-WEB-001). Only
the generated pages handler checks access rules, Guards and form tokens and sets the security
headers, so aicoded check refuses any other Handler, such as a raw mux or a wrapped handler
(E-LINT-004). A page
that needs data from the browser without a reload uses a page call rather than a separate API;
see page calls. An app with no pages passes only RPC; see
calls between apps.
See also
- Access: rules and Guards on the path.
- The request pipeline: what runs, in which order.
- people/pages/users: a layout with a parameter folder and
DefaultRoute. - Add a page: a folder, a template, an access rule and
Data.