Skip to main content

Module routable

Module routable 

Source
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§

RouteMatch
Result of attempting to match a route on a page.
RouteSpec
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§

RouteOutcome
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 of request_path up to a path boundary — i.e. /blog/archive/2026 produces /blog/archive, /blog, / (in that order).
match_routes
Walk a handler’s routes against suffix (the request path with the page’s url_path stripped off — without the leading /). Returns the first matching RouteMatch, or None when 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. Returns None when no route has name or its pattern isn’t reversible (see reverse_pattern). Combine the suffix with the page’s url_path for a full URL — the routable_url() Tera function does exactly that.
reverse_pattern
Best-effort reverse of an anchored regex pattern: substitute captures into each (?P<name>…) group and emit the literal segments between them. Returns None when 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.