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