Tutorial
The language
Pages and routing
A page is a route and what it shows. Each page names its own path, the app shell frames every page, and a layout frames a section.
This chapter covers WebFluent's pages and routes: a page is a route and what it shows. Each page names its own path, so there is no separate route table to keep in step with your pages.
In this chapter:
- the attributes a page takes
- the
appshell that frames every page, and theRouter - links,
navigate()and how the active link is marked - route parameters, query strings and fragments
- layouts, guards and per-page head tags
- a page in another language, with
lang:andtranslates: - the catch-all page
- what runs, and in what order, when a page opens
Declaring a page
A page is a page declaration with a name, a path: and a body. This page answers /about:
page About(path: "/about", title: "About us", description: "Who we are and why we build this.") {
Container {
Heading("About us").h1
Paragraph("We are three people and a dog.")
}
}
The page's header takes these attributes:
| Attribute | Required | Meaning |
|---|---|---|
|
|
yes |
The route: |
|
|
strongly advised |
The |
|
|
strongly advised |
The meta description: the snippet a search result and a link preview show. Keep it under about 160 characters ( |
|
|
The image a shared link previews with, site-relative or absolute | |
|
|
What that image shows, for a reader who cannot see it ( |
|
|
|
|
|
|
|
|
|
|
|
The language the page is written in, when it is not the site's: |
|
|
|
The page this one is a translation of, by name: |
|
|
|
The component that frames the page (Layouts) |
|
|
|
An expression that must hold for the route to render (Guards) |
|
|
|
Where the reader goes when the guard fails. The default is |
|
|
|
The values a static build renders a |
|
|
|
for each |
A route parameter, typed (Route parameters) |
A page without a title: builds with warning S01, and one without a description: with warning S02. The compiler cannot write those for you, and a page without them looks bare when someone shares or searches for it.
Note
Coming from React Router, Vue Router or SvelteKit? There is no route table and no routes/ folder. Each page names its own path:, and the compiler builds the router from every page. See Coming from React.
The app shell
The app declaration is the shell: what every page renders inside, such as a navbar and a footer. The Router marks where the current page goes:
app {
Navbar {
Navbar.Brand { Link("Acme", to: "/") }
Navbar.Links {
Link("Docs", to: "/docs").prefix
Link("Pricing", to: "/pricing")
}
Navbar.Actions { Button("Sign in").sm { on click { navigate("/login") } } }
}
Router
Footer { Text("© Acme").muted.sm }
}
The Router behaves like this:
- It is bare: it takes no children, and it may sit at any depth inside
app(in aRow, aContainer, aStack). - Its route table is built from every page's
path:, ordered by specificity: static segments before:params, and*last. The order you declare pages in can never shadow a route. - A project with no
appdeclaration gets a bare router. Router(transition: .fade, duration: "200ms")animates page changes (Motion).
Links and navigation
A Link is an <a> whose clicks the router handles. To move from code, for example after a button press, call navigate(path):
page Start(path: "/", title: "Start", description: "Where the tour begins.") {
Heading("Start here").h1
Link("Home", to: "/")
Link("Guide", to: "/docs").prefix // also active on /docs/anything
Button("Take the tour") { on click { navigate("/about") } }
}
page Guide(path: "/docs", title: "Guide", description: "The guide.") { Heading("Guide").h1 }
page About(path: "/about", title: "About", description: "Who we are.") { Heading("About").h1 }
The active link
The link whose to: matches the current route carries the class .active and aria-current="page", so you can style it and a screen reader announces it. Two rules widen or narrow the match:
.prefix(the flag foractive: .prefix) also makes a link active on the routes beneath it, which suits a section link such as Guide.- A
to:with a query, such as"/?show=open", is active only when the address carries those values too. A row of filter links then marks the one that is on, and a plain link to the same path gives way to it.
Paths under a sub-path
Write every path from the site's root, "/about", even when the site is served under a sub-path. With build.base_path set to "/docs", the compiler prefixes every Link, every navigate() and every asset for you.
Static and single-page navigation
How a link moves depends on the build:
- In a static build, a link is a real page load, and so is
navigate(). - In a single-page app, a link swaps the page without a reload. Focus moves to the new page's heading, the scroll goes back to the top (or to the
#fragmentthe address names), and the new title is announced.
Route parameters
A :name segment in the path is a typed parameter of the page. You read it as a plain name, or as params.name:
type Post { slug: String, title: String, body: String }
store Posts {
state all: [Post] = [
Post(slug: "hello", title: "Hello", body: "First post."),
Post(slug: "again", title: "Again", body: "Second post.")
]
}
page PostPage(path: "/posts/:slug", title: "Post", description: "One post.", slug: String) {
use Posts
derived post = Posts.all.find(p => p.slug == slug)
if let p = post {
Heading(p.title).h1
Paragraph(p.body)
} else {
Heading("No such post").h1
Text("Nothing lives at /posts/{params.slug}.")
}
}
Every parameter the path names is declared in the page's header with its type: slug: String, or id: Number for a number, which the page then reads as one. A path that names a parameter the header does not declare is R02. A static build renders a :param page once for each value its paths: names (Pre-render a page for each item).
Query strings and fragments
query is the URL's query string, a [String: String], and hash is its #fragment. Reading a key gives a String?, since the address may not carry it, so a page gives it a default with ??. The runtime keeps both current, so a page that reads them follows the address:
page Products(path: "/products", title: "Products", description: "Everything we sell.") {
derived tab = query.tab ?? "all"
derived sort = query.sort ?? "name"
Heading("Products").h1
Row(gap: .sm) {
Link("All", to: "/products?tab=all")
Link("On sale", to: "/products?tab=sale")
}
Text("Showing {tab}, sorted by {sort}; section: {hash}")
}
A query string is not part of the route: /products?tab=sale is the /products page. To change the query from code, call navigate("/products?tab=sale").
The static paint is the HTML the build pre-renders for a page. In it, query and hash are unknown, so anything that depends on them is drawn once the page is live in the browser.
Layouts
A layout is a component that frames a page. You name it with layout:, and the page renders in its default slot. Use a layout for one section's chrome, such as a docs sidebar or an app rail; the app shell is for the whole site's.
In this example, two docs pages share one sidebar and breadcrumb:
component DocsShell(_ crumb: String) {
slot
Row(gap: .lg) {
Sidebar {
Sidebar.Item(to: "/docs") { Text("Guide") }
Sidebar.Item(to: "/docs/reference") { Text("Reference") }
}
Stack {
Breadcrumb {
Breadcrumb.Item(to: "/docs") { Text("Docs") }
Breadcrumb.Item { Text(crumb) }
}
children
}
}
}
page Guide(path: "/docs", title: "Guide", description: "The guide.", layout: DocsShell("Guide")) {
Heading("Guide").h1
}
page Reference(path: "/docs/reference", title: "Reference", description: "The reference.", layout: DocsShell("Reference")) {
Heading("Reference").h1
}
A layout follows these rules:
- The compiler checks the layout's arguments like any component call (
DocsShell("Guide")). - The layout component must declare a default
slot, and placechildrenwhere the page goes. Without theslotline the build stops with errorE104. A component that is only ever called, not named as a layout, needschildrenalone (Slots). - The page's skip link jumps past the layout's chrome to the page's first element. That element gets
id="wf-content"when it has no id of its own.
Guards
A guard keeps a route from rendering until a condition holds. guard: names an expression, usually a store's derived value. When it is false, the reader is sent to redirect: (by default, /):
type User { name: String }
store Auth {
state user: User? = null
derived loggedIn = user != null
action login() { user = User(name: "Sam") }
action logout() { user = null }
}
page Account(path: "/account", title: "Your account", description: "Your account.", guard: Auth.loggedIn, redirect: "/login") {
use Auth
Heading("Welcome back").h1
Button("Sign out") { on click { Auth.logout() } }
}
page Login(path: "/login", title: "Sign in", description: "Sign in.") {
use Auth
Heading("Sign in").h1
Button("Sign in").primary { on click { Auth.login() navigate("/account") } }
}
The browser evaluates the guard on every navigation.
Caution
A guard is a gate in the browser, not a secret. A static build still pre-renders the guarded page's HTML, so keep anything private behind an API that the page asks, and that checks who is asking.
Per-page head tags
A head { } block adds tags of the page's own to the document's <head>. The build writes them into the static paint where it knows the value, the live page keeps them current, and they are removed when the reader leaves the page:
page Share(path: "/share", title: "Share", description: "A page with its own tags.") {
state image = "/og-share.png"
head {
meta(property: "og:image", content: image)
link(rel: "canonical", href: "https://example.com/share")
script(src: "/analytics.js", defer: true)
}
Heading("Share").h1
}
A tag's src: and href: go through the same scheme check as every address, at build time and on the live page, so a value never points one at javascript: or data:. A script(src:) is written out, never read from a value, and a meta(http-equiv: "refresh") may not take its address from one (E107): whoever controls the value would choose what the page runs or where the reader goes.
title: and description: are page attributes, not head tags. From them and the config, the compiler writes the standard tags itself: charset, viewport, description, canonical, Open Graph, Twitter card and JSON-LD.
A page in another language
A page written in a language other than the site's says so with lang:, and names the page it translates with translates:. This site is in English, with its home page in Arabic at /ar:
page Home(path: "/", title: "Home", description: "What we make.") {
Heading("Welcome").h1
}
page HomeAr(path: "/ar", title: "الرئيسية", description: "ما نصنعه.", lang: "ar", translates: Home) {
Heading("أهلاً بك").h1
}
What the two attributes do:
lang:writes the page as<html lang="ar" dir="rtl">, with itsog:localeand its JSON-LD'sinLanguageto match. The router setslanganddirwhen it shows the page, and puts the site's back on a page without one.translates:joins the pages. Each lists the others ashreflangalternates, each at its own address, withx-defaultfor the one in the site's language, so a search engine finds every language.- A
translates:that names no page, or two translations of one page in one language, isR05.
This is different from t() and setLocale, which translate one address in the browser. Publish a page in each language compares the two.
The catch-all page
A page with path: "*" answers every route no other page claims. The router shows it in the browser, and a static host serves it as 404.html:
page NotFound(path: "*", title: "Not found", description: "Nothing lives here.", noindex: true) {
Container {
Heading("Nothing here").h1
Link("Back home", to: "/")
}
}
Set-up code: what runs when a page opens
A page's body is a render block: it declares state, derived values and actions, and lists what to show. The top of the body runs once, when the page renders. A call written there, such as Deploys.load(id), is set-up code: it runs once as the page opens.
type Run { id: String, ok: Bool }
store Deploys {
state rows: [Run] = []
action load(id: String) { rows = [Run(id: id, ok: true)] }
}
page Deploy(path: "/deploys/:id", title: "Deploy", description: "One deploy.", id: String) {
use Deploys
Deploys.load(id)
Heading("Deploy {id}").h1
for row in Deploys.rows by row.id {
Text("{row.id}: {row.ok}")
}
}
The life of a page
A page goes through these stages, in order:
- The route matches. In a split build, the page's chunk loads, and its stylesheet with it.
- The body runs once: each
statetakes its initial value, set-up calls run, and the elements are created. Nothing re-renders after this; whatever reads a state updates on its own. - Each
effectruns, and runs again when what it reads changes. Timers start. - The page is placed. In a single-page app, focus moves to its heading, the scroll goes to the top and the title is announced.
- When the route changes, everything the page created is disposed of: effects, timers, listeners, connections and
.routestores. Theircleanup { }blocks run.
There is no onMount to write. Set-up code runs at stage 2, an effect at stage 3, and after(0) { … } once the page is on screen.
Note
Coming from React? A page's body is not a function called on every render; it runs once. Set-up code does what useEffect(…, []) did, and nothing re-renders after it. See Coming from React.
Quick reference
| Syntax | Meaning |
|---|---|
|
|
A page and its route |
|
|
A typed route parameter, read as |
|
|
The catch-all page, served as |
|
|
The shell around every page, and where the page goes |
|
|
A link, active on its route and the routes beneath it |
|
|
Move to a route from code |
|
|
The query string and the fragment, kept current |
|
|
Frame the page with a component's default slot |
|
|
Render only while a condition holds |
|
|
Tags of the page's own in |
|
|
A page in another language, joined to the page it translates |
The configuration reference covers build.base_path, and Static or single-page covers how each build serves pages.
Common mistakes
A route names a parameter the page does not declare. Each :name in the path is a parameter of the page, and the page must declare it:
page Post(path: "/posts/:slug", title: "Post", description: "One post.") {
Heading("A post").h1
}
Add slug: String to the page's header, beside path:, and read it as slug (R02).
A link to a page that does not exist. The compiler knows every route, so a Link or a navigate() to a path no page answers stops the build:
page Home(path: "/", title: "Home", description: "The front page.") {
Heading("Home").h1
Link("About us", to: "/about")
}
Declare the page, page About(path: "/about", …), or fix the path (R01).
A layout with nowhere to put the page. A layout: component must declare a default slot and place children where the page goes:
component Shell(_ crumb: String) {
Stack {
Text(crumb)
}
}
page Home(path: "/", title: "Home", description: "The front page.", layout: Shell("Home")) {
Heading("Home").h1
}
Add slot at the top of Shell and children inside its Stack (E104).
What you learned
-
Declare a
pagewith itspath:,title:anddescription: -
Frame every page with
appand aRouter, and a section with alayout: -
Read route parameters,
queryandhash, and move withLinkandnavigate() -
Publish a page in another language with
lang:andtranslates: -
Guard a route, add head tags, and answer every other route with
path: "*"