aicoded.dev

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

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

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>
// 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
}

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

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

Markdown · Source on GitHub · framework f46741f