Skip to main content

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}