Skip to main content

PageTypeHandler

Trait PageTypeHandler 

Source
pub trait PageTypeHandler:
    Send
    + Sync
    + 'static {
Show 29 methods // Required methods fn app_label(&self) -> &'static str; fn type_name(&self) -> &'static str; fn verbose_name(&self) -> &'static str; fn default_template(&self) -> &'static str; // Provided methods fn allowed_parent_types(&self) -> &'static [&'static str] { ... } fn allowed_child_types(&self) -> &'static [&'static str] { ... } fn is_leaf(&self) -> bool { ... } fn is_creatable(&self) -> bool { ... } fn icon(&self) -> Option<&'static str> { ... } fn description(&self) -> Option<&'static str> { ... } fn feed_kind(&self) -> Option<&'static str> { ... } fn workflow_slug(&self) -> Option<&'static str> { ... } fn view_restriction(&self) -> Option<TypeViewRestriction> { ... } fn view_mode(&self) -> PageViewMode { ... } fn load_extension<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Value, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn routes(&self) -> Vec<RouteSpec> { ... } fn route_context<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page: &'life2 Page, _matched: &'life3 RouteMatch, ) -> Pin<Box<dyn Future<Output = Result<Map<String, Value>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait { ... } fn public_context<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page: &'life2 Page, ) -> Pin<Box<dyn Future<Output = Result<Map<String, Value>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait { ... } fn children_query<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, pool: &'life1 Pool, page: &'life2 Page, ) -> Pin<Box<dyn Future<Output = Result<Vec<Page>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait { ... } fn extension_fields<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExtensionField>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn widgets<'life0, 'life1, 'async_trait>( &'life0 self, pool: &'life1 Pool, page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<Widget>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn snippet_m2m_relations(&self) -> Vec<(&'static str, &'static str)> { ... } fn preview_extension<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, pool: &'life1 Pool, page_id: i64, form: &'life2 HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<Value, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait { ... } fn save_extension<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, _form: &'life2 HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(), ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait { ... } fn extra_tabs<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<TabSpec>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... } fn inline_panels(&self) -> Vec<InlinePanelSpec> { ... } fn load_inline_panel<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, _panel_name: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Map<String, Value>>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait { ... } fn save_inline_panel<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, _panel_name: &'life2 str, _rows: &'life3 [Map<String, Value>], ) -> Pin<Box<dyn Future<Output = Result<(), ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait { ... } fn display_fields<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<DisplayField>, ExecError>> + Send + 'async_trait>> where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait { ... }
}
Expand description

A page kind registered by user code (e.g. BlogPostPage, LandingPage).

Each impl owns the typed extension table that backs its kind, the template used to render it, its admin form, and the parent/child type whitelist.

Registering. Prefer #[derive(PageType)], which emits this impl plus the inventory registration and forwards the overridable hooks to PageTypeOverrides. A hand-written impl registers with register_page_type! and needs only the four required methods (app_label, type_name, verbose_name, default_template); every other hook has a no-op default.

When hooks run. Render hooks (load_extension, public_context, children_query, routes / route_context) run on every public request for a page of this type. Editor hooks (widgets, extra_tabs, inline_panels, display_fields) run on the admin edit form; save_extension / save_inline_panel on its POST, after the cms_page row is saved; preview_extension on live preview.

Handlers are process-global — instances are constructed via PageTypeHandlerRegistration::factory and live for the lifetime of the binary. The matching DB row in cms_page_type is per-tenant and seeded by crate::ensure_seeded.

Required Methods§

Source

fn app_label(&self) -> &'static str

Logical app this handler belongs to (e.g. "cms_articles"). Lets multiple crates contribute page types without type_name collisions, and groups them in the admin.

Source

fn type_name(&self) -> &'static str

Stable identifier — stored in cms_page_type.type_name. Must be globally unique across the process.

Source

fn verbose_name(&self) -> &'static str

Human-readable label for the admin UI.

Source

fn default_template(&self) -> &'static str

Default Tera template path the renderer should use. A page can override it per row via Page::template_override.

Provided Methods§

Source

fn allowed_parent_types(&self) -> &'static [&'static str]

Page types that are allowed as a parent for instances of this type. Empty slice = no restriction (the child-side guard).

Source

fn allowed_child_types(&self) -> &'static [&'static str]

Page types that are allowed as direct children of instances of this type. Empty slice = no restriction (the parent-side guard). Symmetric with Self::allowed_parent_types: both sides must agree at create / move time.

Source

fn is_leaf(&self) -> bool

Whether this type is a leaf — it accepts no child pages at all. Distinct from allowed_child_types() == [], which means “no restriction” (any type may be a child). Returning true is the first-class way to say “this page can’t have children” without the sentinel hack of whitelisting a non-existent child type. Enforced parent-side at create / move time.

Source

fn is_creatable(&self) -> bool

Whether this type may be created from the admin “Add page” menu. Defaults to true; abstract / programmatically-only types should override to false.

Source

fn icon(&self) -> Option<&'static str>

Material-symbols icon name for the page-type picker tile. Defaults to None — picker renders a generic glyph. Authors set it via #[page_type(icon = "article")] on the #[derive(PageType)] struct, or by overriding this method on hand-rolled handlers.

Source

fn description(&self) -> Option<&'static str>

One-line description shown under verbose_name in the page-type picker. Defaults to None. Authors set it via #[page_type(description = "…")].

Source

fn feed_kind(&self) -> Option<&'static str>

Opt this page type in to a public RSS 2.0 / Atom 1.0 feed (powered by rustango::syndication). The returned slug is the URL path segment under /feed/<slug>/rss.xml + /feed/<slug>/atom.xml; pick something URL-friendly and distinct from other page types’ slugs.

Returning None (the default) means no feed is emitted for this type — its pages still render normally; they just don’t appear in any aggregate feed.

The feed lists every published, indexable crate::Page row of this type in published_at desc order. See crate::feed for the URL shape and content mapping.

Source

fn workflow_slug(&self) -> Option<&'static str>

Opt this page type in to a multi-step approval workflow. Returns the Workflow name of the workflow to apply to pages of this type, or None to leave them on the direct-publish path.

When this returns Some("Editorial review"), the page editor for pages of this type renders a Submit-for-review action that creates a cms_workflow_state row and walks the page through the workflow’s tasks. Pages can only finish a workflow once the final task is approved.

The workflow with the returned name must exist + be active in the tenant’s cms_workflow table — admins create + manage workflows at /cms-admin/workflows. If the named workflow doesn’t exist or is inactive, pages fall back to the direct-publish path.

Source

fn view_restriction(&self) -> Option<TypeViewRestriction>

Gate every page of this type behind an access requirement — the per-type analogue of the per-page Privacy tab. Return None (the default) to leave the type public; return crate::view_restriction::TypeViewRestriction::login to require any authenticated member, or crate::view_restriction::TypeViewRestriction::permission to require one of a set of permission codenames (checked through the framework permission engine).

A page/subtree restriction set on an individual page (or an ancestor) is more specific and overrides this type-level default. The derive forwards to PageTypeOverrides::view_restriction automatically.

Source

fn view_mode(&self) -> PageViewMode

Which representation this type serves on its public URL.

Defaults to crate::page_view::PageViewMode::Auto, which derives the answer from Self::default_template: a blank template means the type is JSON-only, anything else means HTML. Return crate::page_view::PageViewMode::Api to serve JSON at the page’s own URL under Accept: application/json even when a template exists — the template still answers browsers.

Set it declaratively with #[page_type(view_mode = "api")], which also makes the otherwise-mandatory template attribute optional. Without the attribute the derive forwards to PageTypeOverrides::view_mode.

Source

fn load_extension<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Value, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load the typed extension row for a given page id and return it as JSON for the renderer’s Tera context.

The default implementation returns Value::Null — types with no extension table (e.g. a HomePage whose data lives entirely on the base Page row) get a null extension value in the template context.

§Errors

Driver / query failures from the extension lookup.

Source

fn routes(&self) -> Vec<RouteSpec>

URL patterns this page type serves IN ADDITION to its canonical url_path.

Each crate::routable::RouteSpec declares a regex pattern (matched against the suffix BELOW the page’s url_path) and a stable name. When the public resolver can’t find an exact url_path match it walks ancestor candidates and asks each candidate’s handler whether any of its routes accept the remaining suffix. On match, the renderer dispatches to Self::route_context for handler-injected ctx, and the matched crate::routable::RouteMatch is exposed to the template as route_name + route_captures.

Default: empty — page types without routable patterns pay nothing.

Source

fn route_context<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page: &'life2 Page, _matched: &'life3 RouteMatch, ) -> Pin<Box<dyn Future<Output = Result<Map<String, Value>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Handler-computed ctx injected when a routable pattern matched. Mirrors Self::public_context but receives the matched route’s name + named capture groups. Override to load route-specific data — the year’s posts when archive_year matched, the tagged posts when tag matched, etc.

Default returns an empty map; the renderer still threads route_name and route_captures into the context so a handler that only needs the captures (no extra fetches) can stay on the default.

§Errors

Driver / query failures from the route-specific computation.

Source

fn public_context<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page: &'life2 Page, ) -> Pin<Box<dyn Future<Output = Result<Map<String, Value>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Inject handler-computed values into the public render’s Tera context, for hand-rolled data — e.g. a HomePage that exposes a latest_posts list to its template without baking the query into the template layer.

The default returns an empty map; override in PageTypeOverrides (or hand-rolled handlers) to surface extras. Framework keys (page, page_type, extension, children, ancestors, url_prefix, locale, translations, theme_*, _snippets_html, _stream_html, _pages_by_id) are stamped AFTER the handler’s keys, so public_context can’t shadow them — pick distinct names for custom keys.

§Errors

Driver / query failures from the handler-side computation.

Source

fn children_query<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, pool: &'life1 Pool, page: &'life2 Page, ) -> Pin<Box<dyn Future<Output = Result<Vec<Page>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Build the children ctx var the public renderer hands to the page template (by default the live children, newest first) — index-style pages (BlogIndexPage, ArchivePage, …) lean on this to surface only published rows in a meaningful order.

The default returns every immediate child sorted by sort_order, id (matches the pre-existing children shape — drafts INCLUDED, ordering NOT chronological). Overriding handlers typically:

  • filter by status = published
  • filter by expire_at IS NULL OR expire_at > now
  • order by published_at DESC (or sort_order ASC for a curated tree)
  • apply a limit

The result lands in two places in the template context: children (the typed list) AND a thread-local backing the children_filtered(...) Tera function (see crate::children_filtered).

§Errors

Driver / query failures from the page lookup.

Source

fn extension_fields<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExtensionField>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Describe the extension-row’s fields so the admin page-editor can render a form section for them. The default returns an empty list — types without an extension table get no extra inputs in the editor.

page_id is provided so handlers can pre-fill values from the existing row (the typical impl: load the row, then map each column into an ExtensionField with value).

§Errors

Driver / query failures from the extension lookup.

Source

fn widgets<'life0, 'life1, 'async_trait>( &'life0 self, pool: &'life1 Pool, page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<Widget>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Rich-widget alternative to Self::extension_fields. Returns full crate::Widget instances so handlers can expose the entire 26-kind widget catalog (Date, DatetimeTz, Color, Range, Radio, Select, Checkboxes, MultiSelect, Custom, …) instead of being limited to the legacy six ExtensionFieldKind variants.

Default impl delegates to Self::extension_fields + ExtensionField::into_widget, so handlers that haven’t overridden this method keep working unchanged. Handlers that want the new kinds override widgets instead of extension_fields; the admin form-render path always calls widgets, so a single override surfaces every kind in the editor at once.

§Errors

Driver / query failures propagated from the handler-side computation.

Source

fn snippet_m2m_relations(&self) -> Vec<(&'static str, &'static str)>

Declared Page↔Snippet many-to-many relations as (relation_name, snippet_type) pairs. Macro-generated from the struct-level #[page_type(snippet_m2m(name = "Type", …))] attribute; the default is none. The public renderer resolves each relation’s chosen rows into snippet_relations.<name> so templates can iterate the related snippets.

Source

fn preview_extension<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, pool: &'life1 Pool, page_id: i64, form: &'life2 HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<Value, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Build a virtual extension Value from a posted form HashMap without touching the persisted row. Powers the “preview unsaved changes” iframe in the page editor — the renderer substitutes the result for Self::load_extension so the preview reflects the current form state.

Default impl walks Self::widgets and maps each widget’s name to the form value, with kind-aware coercion (booleans from "on"/"true", multi-value kinds parsed as JSON arrays, numeric kinds parsed into serde_json::Number). Handlers whose persisted shape differs from the widget surface should override.

§Errors

Driver / query failures from the widgets lookup (the form-to-JSON mapping itself is infallible).

Source

fn save_extension<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, _form: &'life2 HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(), ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Persist the posted form values into this type’s extension table. Called by the admin’s page-edit POST handler after the canonical cms_page row has been saved. Upsert keyed on page_id is the standard pattern.

form is the full form HashMap; handlers should pull out only the keys whose name they returned from Self::extension_fields.

§Errors

Driver / query failures from the upsert.

Source

fn extra_tabs<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<TabSpec>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Handler-contributed tabs appended to the page-editor’s tab strip after the built-in Content / Promote / Theme / Revisions ones. Each TabSpec carries a stable name (used in the URL hash + localStorage for “remember last active tab”), a label, an optional Material-symbols icon

  • small badge chip, and a pre-rendered HTML body the admin template emits inside the main <form>.

Because custom tab bodies sit inside the canonical form, any <input name="…"> inside one shows up in the HashMap<String, String> handed to Self::save_extension — handlers can persist tab-scoped fields the same way they persist Self::widgets entries.

Default impl returns an empty list — the built-in tabs are always present and self-contained, so handlers that don’t need a custom tab pay nothing.

§Errors

Driver / query failures from the handler-side computation.

Source

fn inline_panels(&self) -> Vec<InlinePanelSpec>

Inline panels — 1-N collections of sub-rows that the page editor renders as a sortable list of cards. Each InlinePanelSpec declares the panel’s stable name, the human label, the per-row fields, and optional cardinality bounds.

Default impl returns an empty list — handlers that don’t use inline panels pay nothing. Handlers that do override this method must also implement Self::load_inline_panel and Self::save_inline_panel for the rows to round-trip.

Source

fn load_inline_panel<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, _panel_name: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Map<String, Value>>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Fetch existing rows for panel_name keyed under page_id. Each returned serde_json::Map is one row; keys match the name of the InlinePanelSpec::fields entries.

Default impl returns an empty list.

§Errors

Driver / query failures from the row lookup.

Source

fn save_inline_panel<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, _panel_name: &'life2 str, _rows: &'life3 [Map<String, Value>], ) -> Pin<Box<dyn Future<Output = Result<(), ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Persist the posted rows for panel_name under page_id. The admin POST handler parses inline-panel form keys (inline__<panel_name>__<row_idx>__<field>) into row dicts and calls this with the full set; the handler is responsible for the upsert / delete-removed semantics. Sort order is the position in the rows slice.

Default impl is a no-op.

§Errors

Driver / query failures from the upsert.

Source

fn display_fields<'life0, 'life1, 'async_trait>( &'life0 self, _pool: &'life1 Pool, _page_id: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<DisplayField>, ExecError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Computed / display-only fields shown in an “At a glance” panel at the top of the page-edit form. Each entry is a pre-rendered HTML chip (the value is | safed into the template) authored by the handler from arbitrary data: row counts, word counts, derived flags, audit timestamps, linked-snippet previews, etc.

This is the first-class hook for read-only computed values in the editor (static help text and plain model fields can’t show them). display_fields runs at edit-form GET, so each value is recomputed every load and reflects the latest DB state.

Default impl returns an empty list — handlers that don’t need it pay nothing.

§Errors

Driver / query failures from any computation the handler runs against the pool.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§