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.
| Hook | When | Signature |
|---|---|---|
AfterPublishPage | When a page goes live | async fn(HookCtx, &Page) |
BeforeServePage | Just before the public renderer fires | async fn(HookCtx, &Page, &HeaderMap) -> Option<Response> |
AdminMenuItem | Registers a sidebar entry | static struct |
PageActionMenuItem | Registers a kebab-menu entry on the page editor | static struct |
PageListingButton | Registers a per-row action on the page tree | static struct |
AdminSearchArea | Registers an extra source for global search | async 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§
- Account
Settings Panel - One panel contributed to the per-user
/cms-admin/mepage. Pre-rendered HTML the template emits via| safe— hosts wire their own POST endpoints (the registry stays read-only). - Admin
Css - 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). - Admin
Menu Item - 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"). - Admin
Search Area - 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. - Admin
Search Hit - One hit row from a plugin-contributed search source.
- After
Publish Page - 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.
- Before
Serve Page - Fired in the public router just after
resolve_pathreturns a page and before the renderer fires. ReturnSome(Response)to short-circuit (redirect, 403, custom render, etc.);Noneto let the normal renderer handle it. - Bulk
Action Spec - Plugin-contributed bulk action declaration.
- Dashboard
Widget - One widget contributed to /cms-admin/dashboard.
renderbuilds 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. - Help
Menu Item - 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).
- Page
Action Menu Item - One kebab-menu entry on the page editor (next to the existing “View live” / “Open preview” / “Form fields” entries).
- Page
Header Button - 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. - Page
Listing Button - One per-row action on the page tree (next to “Edit” / “+ Child” / “Clone” / “Delete”).
- Userbar
Item - Plugin-contributed entry in the on-site editor userbar.
href_templatemay 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
resourcematchesresource. Stable ordering bykey. - dashboard_
widgets - fire_
after_ publish_ page - Run every registered
AfterPublishPagehandler 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
queryand return a flattened(area_label, hits)list. - userbar_
items
Type Aliases§
- Hook
Future - The boxed future an async hook returns. It may borrow the context and its other arguments.