Skip to main content

Crate rustango_cms

Crate rustango_cms 

Source
Expand description

rustango-cms — a multi-tenant, page-tree CMS built on rustango.

Pages live in one tenant-scoped cms_page tree (materialized path, see tree); each page’s kind is a registered PageTypeHandler with its own extension table, template and admin form. Every read and write goes through the tenant’s own pool, and the bundled migrations (see migrations) are tenant-scoped. The same source runs on PostgreSQL, MySQL 8+ and SQLite.

§Entry points

SurfaceWhere
Public site (slug resolver + Tera render, feeds, sitemap, forms)PublicRouter, or the router() / router_at shortcuts
Editor admin at /cms-admin/admin::router, gated by admin::with_login_required; templates via admin::register_templates
Page types#[derive(PageType)] + PageTypeOverrides, or a hand-written PageTypeHandler + register_page_type!
StreamField bodiesblock — the block::Block trait, #[derive(Block)] or register_block!
Reusable content (library / snippets)library (LibraryTypeHandler, register_library_type!) and snippet
Headless JSON API under /api/v2/api::router / api::router_with
MCP server for AI agents at mcp::MCP_PREFIXmcp::router
Per-tenant setup — page-type rows, roles, default locale, host seeders (late tenants seed on first request)ensure_seeded
Extension hooks (publish, serve, admin menu, dashboard)hooks

§Minimal wiring

ⓘ
use std::sync::Arc;

let mut tera = tera::Tera::new("templates/**/*.html")?;
rustango_cms::admin::register_templates(&mut tera)?;
let tera = Arc::new(tera);

let cms_admin = rustango_cms::admin::with_login_required(
    rustango_cms::admin::router(tera.clone()),
    "/login",
);
let app = cms_admin
    .merge(rustango_cms::api::router())
    .merge(rustango_cms::mcp::router(&settings.mcp)) // CSRF-exempt MCP_PREFIX
    .merge(rustango_cms::PublicRouter::new(tera).build());
// Hand `app` to `rustango::manage::Cli::new().tenancy().api(app)`
// and call `rustango_cms::ensure_seeded` from its `.seed(..)` hook.

admin::router is unauthenticated on its own; always wrap it in admin::with_login_required.

§Cargo features

FeatureEffect
postgres (default), sqlite, mysqlDatabase backend, forwarded to rustango
storage_s3S3-compatible media storage for media_storage::install_from_env
cache_cloudflare, cache_varnish, cache_cloudfront, cache_gcp, cache_azureFront-cache purge backends (cache_invalidate)
search_elasticsearchElasticsearch search backend (search_elasticsearch module)
avifAVIF image renditions
test_utilsrustango’s Tenant::for_test for integration tests

Re-exports§

pub use view_restriction::RestrictionKind;
pub use view_restriction::TypeViewRestriction;
pub use category::registered_handlers as registered_taxonomy_handlers;
pub use category::Category;
pub use category::PageCategory;
pub use category::Taxonomy;
pub use category::TaxonomyHandler;
pub use category::TaxonomyHandlerRegistration;
pub use library::ensure_library_type_row;
pub use library::find_handler as find_library_handler;
pub use library::registered_handlers as registered_library_handlers;
pub use library::LibraryType;
pub use library::LibraryTypeHandler;
pub use library::LibraryTypeHandlerRegistration;
pub use library::ListColumn;
pub use library::ListColumnKind;
pub use locale::Locale;
pub use locale_mode::resolve_request_locale;
pub use locale_mode::LocaleMode;
pub use locale_mode::RequestLocale;
pub use media::Media;
pub use media::MediaCollection;
pub use category_translation::CategoryTranslation;
pub use menu_item_translation::MenuItemTranslation;
pub use navigation::Menu;
pub use navigation::MenuItem;
pub use page::Page;
pub use page::PageStatus;
pub use page_type::all_children;
pub use page_type::default_children;
pub use page_type::find_handler;
pub use page_type::published_children;
pub use page_type::published_children_page;
pub use page_type::registered_handlers;
pub use page_type::ChildOrder;
pub use page_type::ChildrenPage;
pub use page_type::DisplayField;
pub use page_type::ExtensionField;
pub use page_type::ExtensionFieldKind;
pub use page_type::InlinePanelSpec;
pub use page_type::InlineRowSaved;
pub use page_type::InlineRowSummary;
pub use page_type::PageTypeHandler;
pub use page_type::PageTypeHandlerRegistration;
pub use page_type::PageTypeOverrides;
pub use page_type::TabSpec;
pub use page_view::Accept;
pub use page_view::PageViewKind;
pub use page_view::PageViewMode;
pub use permissions::user_can;
pub use permissions::user_can_in_collection;
pub use permissions::user_can_matrix;
pub use permissions::Action;
pub use permissions::CollectionPermission;
pub use permissions::PagePermission;
pub use redirect::bump_hit_count as bump_redirect_hit_count;
pub use redirect::find_for_path as find_redirect_for_path;
pub use redirect::Redirect;
pub use revision::Revision;
pub use snippet::Snippet;
pub use theme::emit_css as emit_theme_css;
pub use theme::BrandColor;
pub use theme::Theme;
pub use theme_resolve::resolve_for_page as resolve_theme_for_page;
pub use theme_resolve::ResolvedTheme;
pub use theme_seed::ensure_themes_seeded;
pub use translation::Translation;
pub use page_type_model::PageType;
pub use render::render;
pub use resolver::resolve_path;
pub use router::router;
pub use router::router_at;
pub use router::router_at_cached;
pub use router::router_cached;
pub use router::PublicRouter;
pub use schedule::spawn_schedule_sweeper;
pub use seed::ensure_seeded;
pub use seed::SeedError;
pub use admin::admin_page::find_admin_page;
pub use admin::admin_page::registered_admin_pages;
pub use admin::admin_page::AdminForm;
pub use admin::admin_page::AdminPageCtx;
pub use admin::admin_page::AdminPageHandler;
pub use admin::admin_page::AdminPageHandlerRegistration;
pub use admin::admin_page::SidebarSection;
pub use admin::cms_admin::delete_record;
pub use admin::cms_admin::save_record;
pub use admin::cms_admin::CmsAdmin;
pub use admin::cms_admin::CmsAdminMeta;
pub use admin::cms_admin::CmsAdminOverrides;
pub use admin::cms_admin::CmsAdminPage;
pub use admin::cms_admin::FieldError;
pub use block::find_block;
pub use block::registered_blocks;
pub use block::validate_block_registry;
pub use block::Block;
pub use block::BlockCountConstraint;
pub use block::BlockError;
pub use block::BlockField;
pub use block::BlockFieldMeta;
pub use block::BlockRegistration;
pub use block::BlockRenderCtx;
pub use tree::MaterializedPath;
pub use tree::PathError;
pub use tree_ops::cascade_url_path_to_descendants;
pub use tree_ops::compute_url_path;
pub use tree_ops::rebuild_all_url_paths;
pub use tree_ops::validate_child_placement;
pub use tree_ops::NewPage;
pub use tree_ops::TreeError;
pub use widget::Widget;
pub use widget::WidgetKind;

Modules§

a11y
Server-side accessibility heuristics.
access
Viewer-aware access helpers for public templates (#members).
admin
R-CMS admin section.
admin_bar
The admin bar: a small floating bar on public pages for someone signed in to the CMS admin, with Edit this page and Admin links.
analytics
Default first-party web analytics (#analytics).
api
REST API v2 — public reads plus member login.
auto_menu
auto_menu(parent_id=…, depth=…) Tera function — an automatic menu built from the page tree.
block
StreamField — composable body blocks.
branding
A site’s branding: its name, logo and browser icon, kept in one place (the branding site setting, edited under Settings → Branding) and used everywhere: the admin sidebar and sign-in screens, and the public site’s layout.
breadcrumbs
Breadcrumb engine — walks the page tree once and returns an ordered list of (title, url, is_current) crumbs.
cache_azure
Azure CDN purge backend for crate::cache_invalidate::PageCacheInvalidator.
cache_cloudflare
Cloudflare-purge backend for crate::cache_invalidate::PageCacheInvalidator.
cache_cloudfront
AWS CloudFront invalidator for crate::cache_invalidate::PageCacheInvalidator.
cache_gcp
Google Cloud CDN purge backend for crate::cache_invalidate::PageCacheInvalidator.
cache_invalidate
Targeted page-cache invalidation hook.
cache_varnish
Varnish-purge backend for crate::cache_invalidate::PageCacheInvalidator.
category
Categories & taxonomies — hierarchical categorization, built the same way pages are: real migration-tracked models, not a JSON blob or a config file.
category_translation
Per-field, per-locale translation overrides for categories.
children_filtered
children_filtered(...) Tera helper — a page’s live children, filtered and ordered.
collection_view_restriction
CollectionViewRestriction — gate served media bytes behind a login requirement or group membership check.
comment
Inline comments on the page editor.
config
Process configuration from the environment.
content_checks
Extensible content-checks framework.
date_filters
Tera date filters — parse stringified dates from extension / form values and re-format them for output, fail-soft on unparseable / null / empty input.
dismissible
Per-user persistent banner / announcement dismissals.
editing_session
Concurrent-editor tracking.
embed
Embed provider discovery + responsive render.
error_pages
CMS-editable error pages (404/500/…).
feed
Per-page-type RSS 2.0 + Atom 1.0 feeds — “syndication on demand”, powered by rustango::syndication.
forms
Visual Form Builder.
fragment_cache
Page-keyed template-fragment caching.
hooks
Runtime extension-point registry.
language_switcher
Public language-switcher data for templates.
library
Library — reusable content (renamed from “snippets”).
locale
Locale — per-tenant locale registry.
locale_mode
How the public router resolves which locale a request is asking for.
lock
PageLock — best-effort editor lock on a cms_page row.
macros
Declarative macro for registering a PageTypeHandler.
markdown
Server-side Markdown → HTML rendering for page bodies.
mcp
MCP engine — operate the CMS from an AI agent.
media
Media — per-tenant uploaded files (images + documents).
media_storage
Pluggable storage backend for CMS media.
media_usage
Which media-library pictures and files are in use, and where.
menu_item_translation
Per-field, per-locale translation overrides for menu items.
meta_tags
Tera helper that emits canonical <head> meta tags for a page.
metrics
Content metrics — word count, estimated reading time, and a readability score.
migrations
Embed + materialize the bundled CMS migrations.
mysql_text
Long content columns on MySQL.
navigation
Navigation — tenant-managed named menus with nested items.
notification_pref
Per-user notification preferences.
notify
Notifications — one delivery path, many destinations.
page
Page — the tenant-scoped cms_page row every page shares, whatever its type: tree position (path, depth, parent_id), slug and url_path, PageStatus lifecycle, SEO fields and the page_type_id that selects its PageTypeHandler. Type-specific fields live in the handler’s extension table.
page_builder
Page-type field builder — UI-defined body schemas.
page_log
Per-page audit log.
page_snippet_m2m
Page ↔ Snippet many-to-many relations.
page_subscription
Per-user opt-in subscriptions to page publish events.
page_tag
Page tag system.
page_type
Page types: the PageTypeHandler trait every page kind implements, its inventory registry (find_handler, registered_handlers), and the editor-form types the handler returns (ExtensionField, TabSpec, InlinePanelSpec, DisplayField).
page_type_model
PageType — the per-tenant cms_page_type row that gives each registered PageTypeHandler a stable id for cms_page.page_type_id. Rows are upserted by ensure_seeded.
page_url
pageurl(id=N) Tera helper — resolve a cms_page id to its public URL at render time.
page_view
What a page type serves on its public URL, and how Accept picks.
path_prefix
Sites served under a path on the main domain (example.com/acme/) rather than on a host of their own.
pending_change
Changes to a live page held for review.
perf
Request timing instrumentation — opt-in, off by default.
permissions
Per-page permission engine.
preview_token
Signed preview tokens for decoupled / headless frontends.
preview_url
Preview a draft in a decoupled renderer.
redirect
Editor-managed 301/302 redirects.
reference_index
Generic reference index — "what links here".
render
Render a resolved Page through Tera.
rendition
Image renditions — resized variants of a Media row served at /__media__/<filter_spec>/<media_id>.
rendition_route
Public route for serving image renditions.
resolver
URL → Page resolution.
revision
Revision — versioned snapshots of cms_page rows.
richtext
| richtext Tera filter — {{ page.body | richtext }}.
robots
/robots.txt for the public CMS.
routable
routable_page — routable pages. A single Page row can serve multiple URL patterns under its canonical url_path.
router
Public axum router that the host app mounts.
schedule
Background driver for scheduled publishing and expiry.
search
Database full-text search backend.
search_elasticsearch
Elasticsearch full-text SearchBackend.
search_promotion
Search query log + editor-pinned results.
security_log
Sign-in security log and account lockout (#433).
seed
Per-tenant cms_page_type seeding.
signing
Minimal HMAC-SHA256 used across the CMS for short signed tokens (view-restriction grants, signed rendition URLs).
site
Sites — one tenant, several hostnames, each with its own root page.
site_setting
Per-tenant site settings.
sitemap
/sitemap.xml for the public CMS — adopts rustango::sitemaps.
snippet
Library snippets — reusable, non-page content addressable by slug.
snippet_render
snippet_html(type=…, id=N) Tera helper — per-snippet template rendering.
snippet_translation
Per-field, per-locale translation overrides for snippets.
starter
Starter themes: a site’s first page types, pages, menus and look, created from one JSON seed.
task_kind
Custom workflow task kinds.
task_queue
Pluggable background task queue for CMS heavy work.
template_inspector
Template inspector: shows a signed-in admin which templates rendered a public page, and where each one comes from.
tenant_templates
Per-tenant template overrides, resolved from disk with fallback to the global set.
theme
Visual themes — design tokens stored as data, rendered as CSS variables: a Theme holds surface / semantic colors + typography + radii + shadows; BrandColor rows attach N named brand colors per theme, each emitting its own slug-keyed CSS variable triplet (raw / rgb / contrast) plus an auto-derived 50→950 shade scale.
theme_resolve
Per-request theme resolution.
theme_seed
Bootstrap-time hydration of the six bundled themes + their brand colors into each tenant.
translation
Per-field, per-locale translation overrides.
tree
Materialized-path encoding for the page tree.
tree_build
Turn a flat, parent-linked row set into a nested tree.
tree_ops
Tree mutation + read API on top of Page.
uploaded_file
Scratch storage for multi-step media uploads.
urls
Named URL patterns + Tera helper registration.
userbar
On-site editor userbar.
view_restriction
PageViewRestriction — gate published pages behind a password, a login requirement, or a group membership check.
view_restriction_guard
Public-renderer enforcement for PageViewRestriction.
widget
Widget descriptors — the single primitive both flat extension fields (crate::page_type::ExtensionField) and stream-block fields (crate::block::BlockField::Widget, landing in a later slice) use to describe one form input.
workflow
Multi-step approval workflows.
workflow_mail
Workflow notification helpers.

Macros§

register_account_settings_panel
register_admin_css
Register global admin CSS.
register_admin_js
Register global admin JS.
register_admin_menu_item
register_admin_page
Register a custom admin page. The type must implement AdminPageHandler and Default. Mirrors the register_page_type! / register_library_type! pattern — drop the macro call anywhere in the crate’s source and the page shows up at /cms-admin/x/<slug> with a sidebar entry in its declared section.
register_admin_search_area
register_after_publish_page
Register an AfterPublishPage handler at compile time.
register_before_serve_page
register_block
Register a Block at module-load time. Mirrors the register_widget! / register_page_type! patterns.
register_block_enricher
Register a BlockEnricher at compile time.
register_bulk_action
register_chooser
Register a generic chooser for a #[derive(Model)] type.
register_content_check
Register a ContentCheck implementation.
register_dashboard_widget
register_help_menu_item
register_library_type
Register a library type at compile time. Pair with a #[derive(Default)] impl LibraryTypeHandler block. Mirrors crate::register_page_type!.
register_model_admin
Register a generic admin for a #[derive(Model)] type.
register_notification_channel
Register a NotificationChannel so the admin can configure it.
register_page_action_menu_item
register_page_header_button
register_page_listing_button
register_page_type
Submit a PageTypeHandlerRegistration for $ty to the global inventory.
register_report
Register a Report implementation.
register_site_setting
Register a typed schema for a site-settings scope.
register_sitemap_source
Register a SitemapSource. Pair with a Default impl.
register_task_kind
Macro mirror of crate::register_block!. Hosts call this to publish a custom TaskKind into the runtime registry.
register_taxonomy
Register a custom taxonomy / category vocabulary. The type must implement TaxonomyHandler and Default. Mirrors register_page_type! — drop the call anywhere in the crate’s source and the vocabulary is synced into a cms_taxonomy row at seed and shows up under the admin Taxonomies section.
register_tenant_seeder
Register a TenantSeeder at compile time.
register_userbar_item
register_widget
Register a custom widget at module-load time. Picks up rustango_cms::inventory (re-exported in crate) so callers don’t need their own inventory dep.

Enums§

MessageLevel
Message severity, in five levels.

Derive Macros§

Block
#[derive(Block)] — declarative block definition. Walks #[block(...)] + #[field(widget = …)] attrs to emit the Block trait impl + register_block! inventory submission in one go. Coexists with the Block trait through Rust’s separate macro / type namespaces (same pattern as #[derive(PageType)] alongside PageType). #[derive(Block)] — generates the rustango_cms::Block trait impl from #[block(...)] and #[field(...)] attributes plus a global inventory registration so the block joins the registry at link time.
CmsAdmin
#[derive(CmsAdmin)] — an admin editor (list, search, add, edit, delete) for a #[derive(Model)] type, at /cms-admin/x/<slug>. Fields to edit carry the same #[field(widget = …, label = "…")] attributes as page types; the struct needs Default and an impl rustango_cms::CmsAdminOverrides (empty is fine).
PageType
#[derive(PageType)] — declarative page-type definition. See crate::page_type::PageTypeOverrides for the override trait authors implement alongside. #[derive(PageType)] — generates the rustango_cms::PageTypeHandler trait impl from #[page_type(...)] and #[field(...)] attributes plus a global inventory registration so the type is reachable from rustango_cms::find_handler(type_name).