rustango_cms_macros/lib.rs
1//! `rustango-cms-macros` — the derive macros of rustango-cms. Use them
2//! through the `rustango_cms` re-exports; this crate is not added on its own.
3//!
4//! - `#[derive(PageType)]` walks the struct's `#[page_type(...)]` +
5//! `#[field(...)]` attributes and emits the full `PageTypeHandler`
6//! trait impl + an `inventory::submit!` registration, so the type
7//! joins the global handler registry at link time.
8//! - `#[derive(Block)]` does the same for a StreamField block: a
9//! `#[block(...)]` attribute plus one `#[field(...)]` per child value.
10//!
11//! ## Author surface
12//!
13//! ```ignore
14//! use rustango::Model;
15//! use rustango_cms::{PageType, PageTypeOverrides};
16//!
17//! #[derive(Model, PageType, Default, Debug, Clone, serde::Serialize, serde::Deserialize)]
18//! #[rustango(table = "blog_post_page_ext", app = "blog")]
19//! #[page_type(
20//! type_name = "BlogPostPage",
21//! verbose_name = "Blog post",
22//! template = "blog_post.html",
23//! )]
24//! pub struct BlogPostPage {
25//! #[rustango(primary_key)]
26//! pub id: Auto<i64>,
27//! #[rustango(fk = "cms_page", on = "id", unique)]
28//! pub page_id: i64,
29//! #[field(widget = Markdown, label = "Body", help = "GFM.")]
30//! pub body_markdown: String,
31//! }
32//!
33//! // ONE additional impl block carries every optional override.
34//! impl PageTypeOverrides for BlogPostPage {}
35//! ```
36//!
37//! See `rustango_cms::page_type` for the trait, override trait, and
38//! the full surface authors interact with at runtime.
39
40mod block;
41mod cms_admin;
42mod page_type;
43
44use proc_macro::TokenStream;
45
46/// `#[derive(PageType)]` — generates the `rustango_cms::PageTypeHandler`
47/// trait impl from `#[page_type(...)]` and `#[field(...)]` attributes
48/// plus a global inventory registration so the type is reachable from
49/// `rustango_cms::find_handler(type_name)`.
50///
51/// See module docs for the author-facing surface.
52#[proc_macro_derive(PageType, attributes(page_type, field))]
53pub fn derive_page_type(input: TokenStream) -> TokenStream {
54 let input = syn::parse_macro_input!(input as syn::DeriveInput);
55 page_type::expand(input)
56 .unwrap_or_else(syn::Error::into_compile_error)
57 .into()
58}
59
60/// `#[derive(Block)]` — generates the `rustango_cms::Block` trait
61/// impl from `#[block(...)]` and `#[field(...)]` attributes plus a
62/// global inventory registration so the block joins the registry at
63/// link time.
64///
65/// Author surface:
66///
67/// ```ignore
68/// use rustango_cms::Block;
69///
70/// #[derive(Default, Block)]
71/// #[block(icon = "title", group = "Headings", description = "Section heading.")]
72/// pub struct Heading {
73/// #[field(widget = Text, required)]
74/// pub text: String,
75/// #[field(widget = Select, label = "Level", options(h2 = "H2", h3 = "H3"))]
76/// pub level: String,
77/// }
78/// ```
79///
80/// `type_name` defaults to the snake_case of the struct name;
81/// `verbose_name` defaults to the struct name as written. Override
82/// either via `#[block(type_name = "…")]` / `#[block(verbose_name = "…")]`.
83#[proc_macro_derive(Block, attributes(block, field))]
84pub fn derive_block(input: TokenStream) -> TokenStream {
85 let input = syn::parse_macro_input!(input as syn::DeriveInput);
86 block::expand(input)
87 .unwrap_or_else(syn::Error::into_compile_error)
88 .into()
89}
90
91/// `#[derive(CmsAdmin)]` — an admin editor (list, search, add, edit,
92/// delete) for a `#[derive(Model)]` type, at `/cms-admin/x/<slug>`.
93/// Fields to edit carry the same `#[field(widget = …, label = "…")]`
94/// attributes as page types; the struct needs `Default` and an
95/// `impl rustango_cms::CmsAdminOverrides` (empty is fine).
96#[proc_macro_derive(CmsAdmin, attributes(cms_admin, field))]
97pub fn derive_cms_admin(input: TokenStream) -> TokenStream {
98 let input = syn::parse_macro_input!(input as syn::DeriveInput);
99 cms_admin::expand(input)
100 .unwrap_or_else(syn::Error::into_compile_error)
101 .into()
102}