Skip to main content

rustango_cms/starter/
mod.rs

1//! Starter themes: a site's first page types, pages, menus and look,
2//! created from one JSON seed.
3//!
4//! A theme made by `rcms new --theme <name>` ships a `theme.json` next to
5//! its templates. [`apply`] reads it and, on a site that has no pages yet:
6//!
7//! 1. creates the page types as UI-defined page-builder schemas (no Rust
8//!    model), so editors can change their fields and blocks in the admin;
9//! 2. creates the page tree, published, with each page's content;
10//! 3. creates the menus (`header`, `footer`, …) pointing at those pages;
11//! 4. stores the site settings (`site` scope: name, tagline, footer);
12//! 5. adds the theme's colours and fonts as a theme row and makes it the
13//!    site's default.
14//!
15//! It runs once per site: a `starter` site setting records that it did,
16//! and a site that already has pages is left alone, so an editor's work
17//! is never overwritten.
18//!
19//! [`package`] turns a live site into a theme package (`theme.json` plus
20//! its templates, as a `.zip`) and installs one on another site;
21//! [`cli`] is the `theme pack|install|check` command around it.
22//!
23//! ```ignore
24//! fn seed_theme<'a>(pool: &'a Pool, _org: &'a Org) -> SeedFuture<'a> {
25//!     Box::pin(async move {
26//!         rustango_cms::starter::apply(pool, include_str!("../theme.json"))
27//!             .await
28//!             .map(|_| ())
29//!             .map_err(|e| SeedError::Seeder(e.to_string()))
30//!     })
31//! }
32//! rustango_cms::register_tenant_seeder!(seed_theme);
33//! ```
34//!
35//! ## `theme.json`
36//!
37//! ```json
38//! {
39//!   "name": "Blog",
40//!   "site": { "name": "My blog", "tagline": "…", "footer": "…" },
41//!   "theme": { "base": "paper", "slug": "starter-blog", "name": "Blog",
42//!              "tokens": { "color_link": "#2f6fdd", "font_heading": "…" } },
43//!   "page_types": [
44//!     { "type_name": "Post", "verbose_name": "Post", "template": "post.html",
45//!       "parents": ["Blog"], "children": [], "schema": { "nodes": [ … ] } }
46//!   ],
47//!   "pages": [
48//!     { "key": "home", "type": "Home", "title": "Home", "slug": "",
49//!       "data": { … }, "children": [ { "key": "blog", … } ] }
50//!   ],
51//!   "menus": [
52//!     { "slug": "header", "name": "Header",
53//!       "items": [ { "page": "blog" }, { "label": "GitHub", "url": "https://…" } ] }
54//!   ],
55//!   "error_pages": [
56//!     { "status": 404, "title": "Page not found", "slug": "page-not-found",
57//!       "body": [ { "type": "paragraph", "value": { "body": "…" } } ] }
58//!   ]
59//! }
60//! ```
61//!
62//! `schema` is a page-builder [`Document`](crate::page_builder::Document);
63//! `data` is the page's builder values, where a flexible zone is a list
64//! of `{ "type": …, "value": { … } }` entries (ids are added for you).
65//! `tokens` overrides any column of the `base` preset theme.
66//! `error_pages` become pages of the built-in Error page type under the
67//! home page, served for their status (404, 403, 500 or 503); see
68//! [`errors`]. `media` lists sample pictures that page content uses as
69//! `"@media:<key>"`; see [`media`].
70
71use std::collections::HashMap;
72
73use rustango::core::Column as _;
74use rustango::sql::{Auto, ExecError, FetcherPool as _, Pool};
75use serde::Deserialize;
76use serde_json::{json, Map, Value};
77
78use crate::navigation::{Menu, MenuItem};
79use crate::page::{Page, PageStatus};
80use crate::page_builder::{model as pb, parse_schema, validate_schema};
81use crate::page_type_model::PageType;
82use crate::theme::Theme;
83use crate::tree_ops::{NewPage, TreeError};
84
85pub mod cli;
86pub mod errors;
87pub mod media;
88pub mod package;
89
90pub use errors::ErrorPageSeed;
91pub use media::MediaSeed;
92
93/// Site-setting scope recording that a starter theme was applied.
94pub const MARKER_SCOPE: &str = "starter";
95/// Site-setting scope holding the theme's site name, tagline and footer.
96pub const SITE_SCOPE: &str = "site";
97/// `app_label` of the page types a theme creates: the same label the admin
98/// gives types made in the page-type builder, so they edit and delete alike.
99const UI_APP_LABEL: &str = "cms_ui";
100
101/// What [`apply`] did.
102#[derive(Debug, Clone, PartialEq, Eq)]
103pub enum Outcome {
104    /// The theme was applied; the site now has its pages, menus and look.
105    Applied {
106        page_types: usize,
107        pages: usize,
108        menus: usize,
109        error_pages: usize,
110        /// Sample pictures stored in the media library.
111        media: usize,
112    },
113    /// A starter theme was applied to this site before.
114    AlreadyApplied,
115    /// The site already has pages, so nothing was touched.
116    SiteNotEmpty,
117    /// A package was installed on a site with content: only its look
118    /// changed (see [`package::install`]).
119    Switched {
120        page_types_added: usize,
121        page_types_retemplated: usize,
122        /// Error pages added for statuses the site had none for.
123        error_pages_added: usize,
124    },
125}
126
127#[derive(Debug, thiserror::Error)]
128pub enum StarterError {
129    #[error("theme.json: {0}")]
130    Parse(#[from] serde_json::Error),
131    #[error("theme.json: {0}")]
132    Invalid(String),
133    #[error(transparent)]
134    Db(#[from] ExecError),
135    #[error(transparent)]
136    Tree(#[from] TreeError),
137}
138
139/// A parsed `theme.json`.
140#[derive(Debug, Deserialize)]
141#[serde(deny_unknown_fields)]
142pub struct StarterSeed {
143    pub name: String,
144    #[serde(default)]
145    pub site: Map<String, Value>,
146    /// The site's name, logo and icon (`site_name`, `logo`, `favicon`),
147    /// written to Settings → Branding where it has none yet.
148    #[serde(default)]
149    pub branding: Map<String, Value>,
150    #[serde(default)]
151    pub theme: Option<ThemeSeed>,
152    #[serde(default)]
153    pub page_types: Vec<PageTypeSeed>,
154    #[serde(default)]
155    pub pages: Vec<PageSeed>,
156    #[serde(default)]
157    pub menus: Vec<MenuSeed>,
158    #[serde(default)]
159    pub error_pages: Vec<ErrorPageSeed>,
160    #[serde(default)]
161    pub media: Vec<MediaSeed>,
162}
163
164#[derive(Debug, Deserialize)]
165#[serde(deny_unknown_fields)]
166pub struct ThemeSeed {
167    /// Slug of the preset theme to start from (`paper`, …).
168    pub base: String,
169    pub slug: String,
170    pub name: String,
171    /// Columns of [`Theme`] to override, by name.
172    #[serde(default)]
173    pub tokens: Map<String, Value>,
174}
175
176#[derive(Debug, Deserialize)]
177#[serde(deny_unknown_fields)]
178pub struct PageTypeSeed {
179    pub type_name: String,
180    pub verbose_name: String,
181    /// The public template, resolved against the site's own templates.
182    pub template: String,
183    #[serde(default)]
184    pub parents: Vec<String>,
185    #[serde(default)]
186    pub children: Vec<String>,
187    pub schema: Value,
188}
189
190#[derive(Debug, Deserialize)]
191#[serde(deny_unknown_fields)]
192pub struct PageSeed {
193    /// Name menus use to point at this page.
194    pub key: String,
195    #[serde(rename = "type")]
196    pub type_name: String,
197    pub title: String,
198    #[serde(default)]
199    pub slug: String,
200    #[serde(default)]
201    pub seo_description: String,
202    #[serde(default)]
203    pub in_menu: bool,
204    #[serde(default)]
205    pub data: Value,
206    #[serde(default)]
207    pub children: Vec<PageSeed>,
208}
209
210#[derive(Debug, Deserialize)]
211#[serde(deny_unknown_fields)]
212pub struct MenuSeed {
213    pub slug: String,
214    pub name: String,
215    #[serde(default)]
216    pub items: Vec<MenuItemSeed>,
217}
218
219#[derive(Debug, Deserialize)]
220#[serde(deny_unknown_fields)]
221pub struct MenuItemSeed {
222    /// Empty: the linked page's title.
223    #[serde(default)]
224    pub label: String,
225    /// Key of a page in `pages`.
226    #[serde(default)]
227    pub page: Option<String>,
228    #[serde(default)]
229    pub url: Option<String>,
230    #[serde(default)]
231    pub children: Vec<MenuItemSeed>,
232}
233
234/// Parse and check a `theme.json` without touching a database: every
235/// schema valid, every page of a declared type, every menu link resolving.
236///
237/// # Errors
238/// [`StarterError::Parse`] or [`StarterError::Invalid`] naming the problem.
239pub fn parse(seed_json: &str) -> Result<StarterSeed, StarterError> {
240    let seed: StarterSeed = serde_json::from_str(seed_json)?;
241    check(&seed, &HashMap::new())?;
242    Ok(seed)
243}
244
245/// Apply a starter theme to one site (a tenant pool), once. Its sample
246/// pictures are left out; see [`apply_with_media`].
247///
248/// # Errors
249/// An invalid `theme.json`, or a database error part-way. The steps are
250/// not one transaction: after a failure the site has some pages, so a
251/// retry reports [`Outcome::SiteNotEmpty`] instead of duplicating them.
252pub async fn apply(pool: &Pool, seed_json: &str) -> Result<Outcome, StarterError> {
253    apply_with_media(pool, "", seed_json, &[]).await
254}
255
256/// [`apply`], storing the theme's sample pictures in the site's media
257/// library first. `files` are (file name, bytes) for the `media` entries;
258/// `org_slug` is the site whose media storage they go to.
259///
260/// # Errors
261/// As [`apply`], plus a picture that fails to store.
262pub async fn apply_with_media(
263    pool: &Pool,
264    org_slug: &str,
265    seed_json: &str,
266    files: &[(&str, &[u8])],
267) -> Result<Outcome, StarterError> {
268    let mut seed: StarterSeed = serde_json::from_str(seed_json)?;
269    if crate::site_setting::get(pool, MARKER_SCOPE).await?.is_some() {
270        return Ok(Outcome::AlreadyApplied);
271    }
272    if Page::objects().first(pool).await?.is_some() {
273        return Ok(Outcome::SiteNotEmpty);
274    }
275    check(&seed, &pb::component_map(pool).await?)?;
276
277    let media_ids = media::store(pool, org_slug, &seed.media, files).await?;
278    resolve_media(&mut seed.pages, &media_ids);
279    seed.site.values_mut().for_each(|v| media::resolve(v, &media_ids));
280    seed.branding.values_mut().for_each(|v| media::resolve(v, &media_ids));
281    for error_page in &mut seed.error_pages {
282        media::resolve(&mut error_page.body, &media_ids);
283    }
284
285    // Page types: type name -> (id, published schema version).
286    let mut types: HashMap<String, (i64, i32)> = HashMap::new();
287    for pt in &seed.page_types {
288        types.insert(pt.type_name.clone(), create_page_type(pool, pt).await?);
289    }
290
291    let mut pages: HashMap<String, i64> = HashMap::new();
292    let mut root: Option<Page> = None;
293    for page in &seed.pages {
294        let created = create_page(pool, None, page, &types, &mut pages).await?;
295        root.get_or_insert(created);
296    }
297
298    for menu in &seed.menus {
299        create_menu(pool, menu, &pages).await?;
300    }
301    let error_pages = match &root {
302        Some(root) => errors::create(pool, root, &seed.error_pages).await?,
303        None => 0,
304    };
305
306    if !seed.site.is_empty() {
307        crate::site_setting::upsert(pool, SITE_SCOPE, Value::Object(seed.site.clone())).await?;
308    }
309    if !seed.branding.is_empty() {
310        // Keep anything the site's owner already set.
311        let mut branding = crate::branding::get(pool).await.as_object().cloned().unwrap_or_default();
312        for (key, value) in &seed.branding {
313            let empty = value.as_str().is_some_and(str::is_empty);
314            if !empty && branding.get(key).and_then(Value::as_str).is_none_or(str::is_empty) {
315                branding.insert(key.clone(), value.clone());
316            }
317        }
318        crate::site_setting::upsert(pool, crate::branding::SCOPE, Value::Object(branding)).await?;
319    }
320    if let Some(theme) = &seed.theme {
321        let theme_id = create_theme(pool, theme).await?;
322        if let Some(mut root) = root {
323            root.theme_id = Some(theme_id);
324            root.save(pool).await?;
325        }
326    }
327
328    crate::site_setting::upsert(
329        pool,
330        MARKER_SCOPE,
331        json!({ "theme": seed.name, "applied_at": chrono::Utc::now().to_rfc3339() }),
332    )
333    .await?;
334    Ok(Outcome::Applied {
335        page_types: seed.page_types.len(),
336        pages: pages.len(),
337        menus: seed.menus.len(),
338        error_pages,
339        media: media_ids.len(),
340    })
341}
342
343fn resolve_media(pages: &mut [PageSeed], ids: &HashMap<String, String>) {
344    for page in pages {
345        media::resolve(&mut page.data, ids);
346        resolve_media(&mut page.children, ids);
347    }
348}
349
350/// Everything that can be checked before the first write.
351fn check(
352    seed: &StarterSeed,
353    components: &HashMap<String, crate::page_builder::ComponentEntry>,
354) -> Result<(), StarterError> {
355    let mut problems = type_problems(seed, components);
356    let type_names: Vec<&str> = seed.page_types.iter().map(|pt| pt.type_name.as_str()).collect();
357    let mut keys = Vec::new();
358    collect_pages(&seed.pages, &type_names, &mut keys, &mut problems);
359    for menu in &seed.menus {
360        check_menu_items(&menu.items, &keys, &menu.slug, &mut problems);
361    }
362    if seed.pages.len() > 1 {
363        problems.push("one root page expected (the home page); nest the others under it".into());
364    }
365    if !seed.error_pages.is_empty() && seed.pages.is_empty() {
366        problems.push("error pages need a home page to live under".into());
367    }
368    let home_slugs: Vec<&str> = seed.pages.iter().flat_map(|h| &h.children).map(|c| c.slug.as_str()).collect();
369    problems.extend(errors::problems(&seed.error_pages, &home_slugs));
370    problems.extend(media::problems(seed));
371    if problems.is_empty() {
372        Ok(())
373    } else {
374        Err(StarterError::Invalid(problems.join("; ")))
375    }
376}
377
378/// Only the page types: what installing a package's look needs.
379fn check_types(
380    seed: &StarterSeed,
381    components: &HashMap<String, crate::page_builder::ComponentEntry>,
382) -> Result<(), StarterError> {
383    let mut problems = type_problems(seed, components);
384    problems.extend(errors::problems(&seed.error_pages, &[]));
385    if problems.is_empty() {
386        Ok(())
387    } else {
388        Err(StarterError::Invalid(problems.join("; ")))
389    }
390}
391
392fn type_problems(
393    seed: &StarterSeed,
394    components: &HashMap<String, crate::page_builder::ComponentEntry>,
395) -> Vec<String> {
396    let mut problems = Vec::new();
397    for pt in &seed.page_types {
398        if crate::page_type::find_handler(&pt.type_name).is_some() {
399            problems.push(format!(
400                "page type `{}` is also defined in code; pick another name",
401                pt.type_name
402            ));
403        }
404        match parse_schema(&pt.schema) {
405            Ok(doc) => problems.extend(
406                validate_schema(&doc, components)
407                    .into_iter()
408                    .map(|p| format!("page type `{}`: {p}", pt.type_name)),
409            ),
410            Err(e) => problems.push(format!("page type `{}`: {e}", pt.type_name)),
411        }
412    }
413    problems
414}
415
416fn collect_pages<'a>(
417    pages: &'a [PageSeed],
418    type_names: &[&str],
419    keys: &mut Vec<&'a str>,
420    problems: &mut Vec<String>,
421) {
422    for page in pages {
423        if !type_names.contains(&page.type_name.as_str()) {
424            problems.push(format!("page `{}` uses undeclared type `{}`", page.key, page.type_name));
425        }
426        if keys.contains(&page.key.as_str()) {
427            problems.push(format!("page key `{}` is used twice", page.key));
428        }
429        keys.push(&page.key);
430        collect_pages(&page.children, type_names, keys, problems);
431    }
432}
433
434fn check_menu_items(items: &[MenuItemSeed], keys: &[&str], menu: &str, problems: &mut Vec<String>) {
435    for item in items {
436        match (&item.page, &item.url) {
437            (Some(p), None) if !keys.contains(&p.as_str()) => {
438                problems.push(format!("menu `{menu}` links to unknown page `{p}`"));
439            }
440            (Some(_), Some(_)) => {
441                problems.push(format!("menu `{menu}`: an item has both `page` and `url`"));
442            }
443            (None, None) if item.label.is_empty() => {
444                problems.push(format!("menu `{menu}`: an item has no page, url or label"));
445            }
446            _ => {}
447        }
448        check_menu_items(&item.children, keys, menu, problems);
449    }
450}
451
452async fn create_page_type(pool: &Pool, seed: &PageTypeSeed) -> Result<(i64, i32), StarterError> {
453    let mut row = PageType {
454        id: Auto::Unset,
455        app_label: UI_APP_LABEL.to_owned(),
456        type_name: seed.type_name.clone(),
457        verbose_name: seed.verbose_name.clone(),
458        default_template: seed.template.clone(),
459        view_mode: "auto".to_owned(),
460        is_creatable: true,
461        allowed_parent_types: json!(seed.parents),
462        allowed_child_types: json!(seed.children),
463        workflow: String::new(),
464        created_at: Auto::Unset,
465        updated_at: Auto::Unset,
466    };
467    row.insert(pool).await?;
468    let id = *row
469        .id
470        .get()
471        .ok_or_else(|| StarterError::Invalid(format!("no id for page type `{}`", seed.type_name)))?;
472    pb::save_draft(pool, id, seed.schema.clone(), None).await?;
473    let published = pb::publish(pool, id)
474        .await?
475        .ok_or_else(|| StarterError::Invalid(format!("page type `{}` did not publish", seed.type_name)))?;
476    Ok((id, published.version))
477}
478
479fn create_page<'a>(
480    pool: &'a Pool,
481    parent: Option<&'a Page>,
482    seed: &'a PageSeed,
483    types: &'a HashMap<String, (i64, i32)>,
484    pages: &'a mut HashMap<String, i64>,
485) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Page, StarterError>> + Send + 'a>> {
486    Box::pin(async move {
487        let (type_id, version) = types[&seed.type_name];
488        let mut new = NewPage::new(type_id, &seed.title, &seed.slug).with_status(PageStatus::Published);
489        if !seed.seo_description.is_empty() {
490            new = new.with_seo(&seed.title, &seed.seo_description);
491        }
492        let mut page = match parent {
493            Some(parent) => Page::create_child_pool(pool, parent, new).await?,
494            None => Page::create_root_pool(pool, new).await?,
495        };
496        if seed.in_menu {
497            page.show_in_menus = true;
498            page.save(pool).await?;
499        }
500        let id = *page.id.get().ok_or(TreeError::MissingId)?;
501        if !seed.data.is_null() {
502            let data = with_block_ids(&seed.data, &seed.key);
503            pb::upsert_data(pool, id, version, json!({}), data).await?;
504        }
505        crate::revision::capture(pool, &page, None).await?;
506        pages.insert(seed.key.clone(), id);
507        for child in &seed.children {
508            create_page(pool, Some(&page), child, types, pages).await?;
509        }
510        Ok(page)
511    })
512}
513
514/// Give every entry of a flexible zone (a list of `{type, value}`
515/// objects) a stable id unique within the page, as the editor does.
516fn with_block_ids(data: &Value, page_key: &str) -> Value {
517    let Value::Object(fields) = data else {
518        return data.clone();
519    };
520    let mut out = fields.clone();
521    for (field, value) in &mut out {
522        if let Value::Array(entries) = value {
523            for (n, entry) in entries.iter_mut().enumerate() {
524                if let Value::Object(e) = entry {
525                    if e.contains_key("type") && !e.contains_key("id") {
526                        e.insert("id".into(), json!(format!("{page_key}-{field}-{n}")));
527                    }
528                }
529            }
530        }
531    }
532    Value::Object(out)
533}
534
535async fn create_menu(
536    pool: &Pool,
537    seed: &MenuSeed,
538    pages: &HashMap<String, i64>,
539) -> Result<(), StarterError> {
540    let mut menu = Menu {
541        id: Auto::Unset,
542        slug: seed.slug.clone(),
543        name: seed.name.clone(),
544        created_at: Auto::Unset,
545    };
546    menu.save(pool).await?;
547    let menu_id = *menu.id.get().ok_or(TreeError::MissingId)?;
548    create_menu_items(pool, menu_id, None, &seed.items, pages).await
549}
550
551fn create_menu_items<'a>(
552    pool: &'a Pool,
553    menu_id: i64,
554    parent_id: Option<i64>,
555    items: &'a [MenuItemSeed],
556    pages: &'a HashMap<String, i64>,
557) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), StarterError>> + Send + 'a>> {
558    Box::pin(async move {
559        for (n, seed) in items.iter().enumerate() {
560            let mut item = MenuItem {
561                id: Auto::Unset,
562                menu_id,
563                parent_id,
564                sort_order: i32::try_from((n + 1) * 10).unwrap_or(i32::MAX),
565                label: seed.label.clone(),
566                page_id: seed.page.as_ref().and_then(|k| pages.get(k).copied()),
567                external_url: seed.url.clone(),
568                open_in_new_tab: false,
569            };
570            item.save(pool).await?;
571            if !seed.children.is_empty() {
572                let id = *item.id.get().ok_or(TreeError::MissingId)?;
573                create_menu_items(pool, menu_id, Some(id), &seed.children, pages).await?;
574            }
575        }
576        Ok(())
577    })
578}
579
580/// Copy the `base` preset (or update the theme with the same slug, when a
581/// package is installed again), apply the token overrides, and make it the
582/// site's default public theme.
583async fn create_theme(pool: &Pool, seed: &ThemeSeed) -> Result<i64, StarterError> {
584    let existing = Theme::objects()
585        .where_(Theme::slug.eq(seed.slug.clone()))
586        .first(pool)
587        .await?;
588    let base = match &existing {
589        Some(row) => row.clone(),
590        None => Theme::objects()
591            .where_(Theme::slug.eq(seed.base.clone()))
592            .first(pool)
593            .await?
594            .ok_or_else(|| StarterError::Invalid(format!("no preset theme `{}`", seed.base)))?,
595    };
596    let mut fields = match serde_json::to_value(&base)? {
597        Value::Object(map) => map,
598        _ => return Err(StarterError::Invalid("theme did not serialize to an object".into())),
599    };
600    for (key, value) in &seed.tokens {
601        if !fields.contains_key(key) || matches!(key.as_str(), "id" | "slug" | "created_at" | "updated_at") {
602            return Err(StarterError::Invalid(format!("theme token `{key}` is not a theme setting")));
603        }
604        fields.insert(key.clone(), value.clone());
605    }
606    fields.insert("slug".into(), json!(seed.slug));
607    fields.insert("name".into(), json!(seed.name));
608    let mut theme: Theme = serde_json::from_value(Value::Object(fields))?;
609    theme.is_default = true;
610    if existing.is_some() {
611        theme.save(pool).await?;
612    } else {
613        theme.id = Auto::Unset;
614        theme.created_at = Auto::Unset;
615        theme.updated_at = Auto::Unset;
616        theme.is_admin_default = false;
617        theme.insert(pool).await?;
618    }
619    let id = *theme.id.get().ok_or(TreeError::MissingId)?;
620    // One public default: clear the flag on every other theme.
621    for mut other in Theme::objects().fetch(pool).await? {
622        if other.is_default && other.id.get().copied() != Some(id) {
623            other.is_default = false;
624            other.save(pool).await?;
625        }
626    }
627    Ok(id)
628}