Skip to main content

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 page_type;
42
43use proc_macro::TokenStream;
44
45/// `#[derive(PageType)]` — generates the `rustango_cms::PageTypeHandler`
46/// trait impl from `#[page_type(...)]` and `#[field(...)]` attributes
47/// plus a global inventory registration so the type is reachable from
48/// `rustango_cms::find_handler(type_name)`.
49///
50/// See module docs for the author-facing surface.
51#[proc_macro_derive(PageType, attributes(page_type, field))]
52pub fn derive_page_type(input: TokenStream) -> TokenStream {
53    let input = syn::parse_macro_input!(input as syn::DeriveInput);
54    page_type::expand(input)
55        .unwrap_or_else(syn::Error::into_compile_error)
56        .into()
57}
58
59/// `#[derive(Block)]` — generates the `rustango_cms::Block` trait
60/// impl from `#[block(...)]` and `#[field(...)]` attributes plus a
61/// global inventory registration so the block joins the registry at
62/// link time.
63///
64/// Author surface:
65///
66/// ```ignore
67/// use rustango_cms::Block;
68///
69/// #[derive(Default, Block)]
70/// #[block(icon = "title", group = "Headings", description = "Section heading.")]
71/// pub struct Heading {
72///     #[field(widget = Text, required)]
73///     pub text: String,
74///     #[field(widget = Select, label = "Level", options(h2 = "H2", h3 = "H3"))]
75///     pub level: String,
76/// }
77/// ```
78///
79/// `type_name` defaults to the snake_case of the struct name;
80/// `verbose_name` defaults to the struct name as written. Override
81/// either via `#[block(type_name = "…")]` / `#[block(verbose_name = "…")]`.
82#[proc_macro_derive(Block, attributes(block, field))]
83pub fn derive_block(input: TokenStream) -> TokenStream {
84    let input = syn::parse_macro_input!(input as syn::DeriveInput);
85    block::expand(input)
86        .unwrap_or_else(syn::Error::into_compile_error)
87        .into()
88}