Expand description
routable_page — routable pages. A single Page row can serve multiple URL patterns
under its canonical url_path.
§Why
Archive / category index pages typically own a stable canonical
URL (/blog/) plus a family of sub-paths the framework’s slug
resolver shouldn’t have to materialize as real cms_page rows
— /blog/archive/2026/, /blog/tag/rust/, etc. The
routable-page surface lets the handler declare those patterns
and serve them through the same Tera template (with the
capture groups available in the context).
§API
Handlers override crate::PageTypeHandler::routes to return
a list of RouteSpec entries. Each spec carries a regex
pattern (matched against the suffix BELOW the page’s
url_path) and a stable name. When the public router can’t
find an exact url_path match, it walks ancestor candidates
looking for a handler whose routes match the remaining suffix.
On match, the matched Page is rendered with two extra ctx
keys: route_name (the matched RouteSpec::name) and
route_captures (a {name → value} map of regex named groups).
Handlers can also override crate::PageTypeHandler::route_context
to inject route-specific data (e.g. fetch the year’s posts when
archive_year matched) — the returned map is merged into the
Tera context before render. Same precedence rule as
crate::PageTypeHandler::public_context: framework
keys land last and win every collision.
Structs§
- Route
Match - Result of attempting to match a route on a page.
- Route
Spec - A single named URL pattern. The pattern is anchored on both
ends (
^…$) by the constructor; callers can lean on^/$themselves but don’t have to.
Enums§
- Route
Outcome - What a matched routable pattern renders — see
crate::PageTypeHandler::route_outcome.
Functions§
- ancestor_
prefixes - Compute the parent-prefix candidates from
request_path, ordered from longest (most specific) to shortest (root). Each candidate is the prefix ofrequest_pathup to a path boundary — i.e./blog/archive/2026produces/blog/archive,/blog,/(in that order). - match_
routes - Walk a handler’s routes against
suffix(the request path with the page’surl_pathstripped off — without the leading/). Returns the first matchingRouteMatch, orNonewhen no route accepts the suffix. - register_
tera_ function - Register the
routable_url(…)Tera function. Two call shapes (extra kwargs are the named captures): - reverse
- Reverse a named route into the URL suffix below the page’s
url_path. ReturnsNonewhen no route hasnameor its pattern isn’t reversible (seereverse_pattern). Combine the suffix with the page’surl_pathfor a full URL — theroutable_url()Tera function does exactly that. - reverse_
pattern - Best-effort reverse of an anchored regex
pattern: substitutecapturesinto each(?P<name>…)group and emit the literal segments between them. ReturnsNonewhen the pattern can’t be reversed unambiguously — a non-named group, a quantified group, a character class / metacharacter in the literal text (\d,.,+,[,|, …), or a capture with no supplied value.