Skip to main content

Module hooks

Module hooks 

Source
Expand description

Runtime extension-point registry.

Hooks are typed: each hook has a precise signature, and registration is compile-time via inventory::submit! rather than runtime HashMap<&str, Box<dyn Fn>>. Plugins crate-side submit! a handler; CMS-side call sites collect every registered handler and fan out.

§Available hooks

The v1 surface is intentionally narrow — the 6 hooks below cover the common plugin use cases. More can land as customers ask.

HookWhenSignature
AfterPublishPageWhen a page goes liveasync fn(HookCtx, &Page)
BeforeServePageJust before the public renderer firesasync fn(HookCtx, &Page, &HeaderMap) -> Option<Response>
AdminMenuItemRegisters a sidebar entrystatic struct
PageActionMenuItemRegisters a kebab-menu entry on the page editorstatic struct
PageListingButtonRegisters a per-row action on the page treestatic struct
AdminSearchAreaRegisters an extra source for global searchasync fn returning hits

§Registering

The four behavioural hooks (AfterPublishPage, BeforeServePage, AdminSearchArea, DashboardWidget) are async and get a HookCtx: the tenant’s pool, its slug and the acting user. The rest are static descriptors.

ⓘ
use rustango_cms::hooks::{HookCtx, HookFuture};
use rustango_cms::page::Page;

fn purge_cdn<'a>(ctx: HookCtx<'a>, page: &'a Page) -> HookFuture<'a, ()> {
    Box::pin(async move {
        tracing::info!(tenant = ctx.tenant, "purging {}", page.url_path);
        // …an async HTTP call, a query on ctx.pool…
    })
}
rustango_cms::register_after_publish_page!(purge_cdn);

§Failure semantics

Hooks fire in registration order. A panicking hook does NOT abort the request — the panic is caught (across its awaits too), logged, and the next handler runs. BeforeServePage can return Some(Response) to short-circuit the renderer.

Structs§

AccountSettingsPanel
One panel contributed to the per-user /cms-admin/me page. Pre-rendered HTML the template emits via | safe — hosts wire their own POST endpoints (the registry stays read-only).
AdminCss
A blob of CSS injected into every admin page’s <head>. The string is emitted verbatim inside a <style> tag (host-trusted), so plugins can restyle the chrome, hide elements, or theme their own admin pages without shipping a separate stylesheet route.
AdminJs
A blob of JS injected just before </body> on every admin page. Emitted verbatim inside a <script> tag (host-trusted).
AdminMenuItem
One sidebar entry contributed by a plugin. Renders below the built-in Settings section. The icon name is a Material-symbols glyph (e.g. "analytics", "chat", "science").
AdminSearchArea
Plugin-contributed search source for /cms-admin/search. Receives the query string (and the tenant’s pool, so it can query); returns up to N hits to merge into the global search response.
AdminSearchHit
One hit row from a plugin-contributed search source.
AfterPublishPage
Fired when a page goes live: an editor’s save, a bulk publish, a workflow approval or the schedule sweep. Use for side effects — purge a CDN, ping a webhook, push to a feed indexer.
BeforeServePage
Fired in the public router just after resolve_path returns a page and before the renderer fires. Return Some(Response) to short-circuit (redirect, 403, custom render, etc.); None to let the normal renderer handle it.
BulkActionSpec
Plugin-contributed bulk action declaration.
DashboardWidget
One widget contributed to /cms-admin/dashboard. render builds its HTML fragment per request, with the tenant’s pool and the viewer, so it can show live numbers (charts, counts, recent rows…). The HTML is inserted as is: escape anything that came from users.
HelpMenuItem
One sidebar entry rendered under a dedicated “Help” section. Same field shape as AdminMenuItem — kept distinct so plugins can contribute docs / shortcuts links without polluting the generic plugin section.
HookCtx
What an async hook is told about the request it runs in (#686).
PageActionMenuItem
One kebab-menu entry on the page editor (next to the existing “View live” / “Open preview” / “Form fields” entries).
PageHeaderButton
One button rendered alongside Save / Publish on the page editor header. Differs from PageActionMenuItem — that lives inside the kebab dropdown; this is a top-level button always visible.
PageListingButton
One per-row action on the page tree (next to “Edit” / “+ Child” / “Clone” / “Delete”).
UserbarItem
Plugin-contributed entry in the on-site editor userbar. href_template may include {page_id} — the renderer substitutes the live page id (or empty string when no page context).

Constants§

HOOK_TIMEOUT
How long one hook may run. Hooks sit on request paths (a page view, a save), so a hung call in one must not hang the request.

Functions§

account_settings_panels
admin_css
Every registered global admin CSS blob, in registration order.
admin_js
Every registered global admin JS blob, in registration order.
admin_menu_items
Collect every registered AdminMenuItem for the sidebar templates. Stable ordering by key.
bulk_actions_for
Every plugin-contributed bulk action whose resource matches resource. Stable ordering by key.
dashboard_widgets
fire_after_publish_page
Run every registered AfterPublishPage handler in registration order. Panics are caught + logged so one buggy plugin can’t break the publish path.
fire_before_serve_page
Fan out: returns the first short-circuit response or None.
help_menu_items
page_action_menu_items
Collect every registered PageActionMenuItem, with the page id interpolated into each entry’s href_template.
page_header_buttons
Resolve every registered header button against page_id, substituting {page_id} into each href.
page_listing_buttons
page_listing_buttons_raw
Collect raw page-listing buttons (no {page_id} substitution). Used by the page-list template which loops over rows and does the substitution per row inside Tera.
render_dashboard_widgets
Render every dashboard widget, sorted by key: (widget, html). A widget whose render panics is left out.
run_admin_search_areas
Run every registered AdminSearchArea against query and return a flattened (area_label, hits) list.
userbar_items

Type Aliases§

HookFuture
The boxed future an async hook returns. It may borrow the context and its other arguments.