rustango_cms/macros.rs
1//! Declarative macro for registering a [`PageTypeHandler`].
2//!
3//! [`PageTypeHandler`]: crate::PageTypeHandler
4
5/// Submit a [`PageTypeHandlerRegistration`] for `$ty` to the global
6/// inventory.
7///
8/// `$ty` must implement both [`PageTypeHandler`] and [`Default`] —
9/// the macro instantiates one through `<$ty>::default()` per call to
10/// [`registered_handlers`].
11///
12/// # Example
13///
14/// ```ignore
15/// use rustango_cms::{register_page_type, PageTypeHandler};
16///
17/// #[derive(Default)]
18/// pub struct ArticlePage;
19///
20/// #[async_trait::async_trait]
21/// impl PageTypeHandler for ArticlePage {
22/// fn app_label(&self) -> &'static str { "blog" }
23/// fn type_name(&self) -> &'static str { "ArticlePage" }
24/// fn verbose_name(&self) -> &'static str { "Article" }
25/// fn default_template(&self) -> &'static str { "blog/article.html" }
26/// }
27///
28/// register_page_type!(ArticlePage);
29/// ```
30///
31/// ## Per-type extension tables
32///
33/// For typed extension data (e.g. an article's body, hero image),
34/// author a sibling `#[derive(Model)]` struct with a one-to-one FK
35/// back to `cms_page`:
36///
37/// ```ignore
38/// use rustango::sql::Auto;
39/// use rustango::Model;
40///
41/// #[derive(Model)]
42/// #[rustango(table = "cms_article_page", app = "blog")]
43/// pub struct ArticlePageExt {
44/// #[rustango(primary_key, fk = "cms_page", on = "id", unique)]
45/// pub page_id: i64,
46///
47/// pub body_markdown: String,
48/// pub hero_image: Option<String>,
49/// }
50/// ```
51///
52/// The host crate ships this in its own `migrations/` directory;
53/// `discover_migration_dirs` picks it up alongside the framework's.
54/// Override `PageTypeHandler::load_extension` to fetch the row and
55/// return it as JSON for the renderer's Tera context.
56///
57/// [`PageTypeHandler`]: crate::PageTypeHandler
58/// [`PageTypeHandlerRegistration`]: crate::PageTypeHandlerRegistration
59/// [`registered_handlers`]: crate::registered_handlers
60#[macro_export]
61macro_rules! register_page_type {
62 ($ty:ty) => {
63 $crate::inventory::submit! {
64 $crate::PageTypeHandlerRegistration {
65 factory: || ::std::boxed::Box::new(<$ty>::default()),
66 }
67 }
68 };
69}
70
71/// Register a custom admin page. The type must implement
72/// [`AdminPageHandler`](crate::admin::admin_page::AdminPageHandler)
73/// and `Default`. Mirrors the
74/// [`register_page_type!`] / [`register_library_type!`](crate::register_library_type!) pattern —
75/// drop the macro call anywhere in the crate's source and the page
76/// shows up at `/cms-admin/x/<slug>` with a sidebar entry in its
77/// declared section.
78///
79/// ```ignore
80/// use rustango_cms::register_admin_page;
81/// use rustango_cms::admin::admin_page::{AdminPageHandler, AdminPageCtx, SidebarSection};
82///
83/// #[derive(Default)]
84/// pub struct ReportsDashboard;
85///
86/// #[async_trait::async_trait]
87/// impl AdminPageHandler for ReportsDashboard {
88/// fn slug(&self) -> &'static str { "reports" }
89/// fn label(&self) -> &'static str { "Reports" }
90/// fn icon(&self) -> Option<&'static str> { Some("insights") }
91/// fn section(&self) -> SidebarSection { SidebarSection::Site }
92/// async fn render(&self, _ctx: AdminPageCtx<'_>) -> axum::response::Response {
93/// todo!()
94/// }
95/// }
96///
97/// register_admin_page!(ReportsDashboard);
98/// ```
99#[macro_export]
100macro_rules! register_admin_page {
101 ($ty:ty) => {
102 $crate::inventory::submit! {
103 $crate::admin::admin_page::AdminPageHandlerRegistration {
104 factory: || ::std::boxed::Box::new(<$ty>::default()),
105 }
106 }
107 };
108}
109
110/// Register a custom taxonomy / category vocabulary. The type must
111/// implement [`TaxonomyHandler`](crate::category::TaxonomyHandler) and
112/// `Default`. Mirrors [`register_page_type!`] — drop the call anywhere in
113/// the crate's source and the vocabulary is synced into a `cms_taxonomy`
114/// row at seed and shows up under the admin **Taxonomies** section.
115///
116/// Extra typed fields go in the handler's own per-type extension table
117/// (unique `category_id` FK), the same way a page type extends `cms_page`.
118///
119/// ```ignore
120/// use rustango_cms::register_taxonomy;
121/// use rustango_cms::category::TaxonomyHandler;
122///
123/// #[derive(Default)]
124/// pub struct RegionTaxonomy;
125/// impl TaxonomyHandler for RegionTaxonomy {
126/// fn slug(&self) -> &'static str { "region" }
127/// fn verbose_name(&self) -> &'static str { "Regions" }
128/// }
129/// register_taxonomy!(RegionTaxonomy);
130/// ```
131#[macro_export]
132macro_rules! register_taxonomy {
133 ($ty:ty) => {
134 $crate::inventory::submit! {
135 $crate::category::TaxonomyHandlerRegistration {
136 factory: || ::std::boxed::Box::new(<$ty>::default()),
137 }
138 }
139 };
140}