Skip to main content

Module starter

Module starter 

Source
Expand description

Starter themes: a site’s first page types, pages, menus and look, created from one JSON seed.

A theme made by rcms new --theme <name> ships a theme.json next to its templates. apply reads it and, on a site that has no pages yet:

  1. creates the page types as UI-defined page-builder schemas (no Rust model), so editors can change their fields and blocks in the admin;
  2. creates the page tree, published, with each page’s content;
  3. creates the menus (header, footer, …) pointing at those pages;
  4. stores the site settings (site scope: name, tagline, footer);
  5. adds the theme’s colours and fonts as a theme row and makes it the site’s default.

It runs once per site: a starter site setting records that it did, and a site that already has pages is left alone, so an editor’s work is never overwritten.

package turns a live site into a theme package (theme.json plus its templates, as a .zip) and installs one on another site; cli is the theme pack|install|check command around it.

ⓘ
fn seed_theme<'a>(pool: &'a Pool, _org: &'a Org) -> SeedFuture<'a> {
    Box::pin(async move {
        rustango_cms::starter::apply(pool, include_str!("../theme.json"))
            .await
            .map(|_| ())
            .map_err(|e| SeedError::Seeder(e.to_string()))
    })
}
rustango_cms::register_tenant_seeder!(seed_theme);

§theme.json

{
  "name": "Blog",
  "site": { "name": "My blog", "tagline": "…", "footer": "…" },
  "theme": { "base": "paper", "slug": "starter-blog", "name": "Blog",
             "tokens": { "color_link": "#2f6fdd", "font_heading": "…" } },
  "page_types": [
    { "type_name": "Post", "verbose_name": "Post", "template": "post.html",
      "parents": ["Blog"], "children": [], "schema": { "nodes": [ … ] } }
  ],
  "pages": [
    { "key": "home", "type": "Home", "title": "Home", "slug": "",
      "data": { … }, "children": [ { "key": "blog", … } ] }
  ],
  "menus": [
    { "slug": "header", "name": "Header",
      "items": [ { "page": "blog" }, { "label": "GitHub", "url": "https://…" } ] }
  ],
  "error_pages": [
    { "status": 404, "title": "Page not found", "slug": "page-not-found",
      "body": [ { "type": "paragraph", "value": { "body": "…" } } ] }
  ]
}

schema is a page-builder Document; data is the page’s builder values, where a flexible zone is a list of { "type": …, "value": { … } } entries (ids are added for you). tokens overrides any column of the base preset theme. error_pages become pages of the built-in Error page type under the home page, served for their status (404, 403, 500 or 503); see errors. media lists sample pictures that page content uses as "@media:<key>"; see media.

Re-exports§

pub use errors::ErrorPageSeed;
pub use media::MediaSeed;

Modules§

cli
cargo run -- theme …: pack a site into a theme package, install one, or check one.
errors
A theme’s error pages: what visitors see on a missing page (404), a refused one (403), a server failure (500) or maintenance (503).
media
A theme’s sample pictures: the media entries of theme.json, stored in the site’s media library when the theme is applied, and the "@media:<key>" references in page content that point at them.
package
Theme packages: a site’s look (and optionally its pages) as one .zip that another site installs.

Structs§

MenuItemSeed
MenuSeed
PageSeed
PageTypeSeed
StarterSeed
A parsed theme.json.
ThemeSeed

Enums§

Outcome
What apply did.
StarterError

Constants§

MARKER_SCOPE
Site-setting scope recording that a starter theme was applied.
SITE_SCOPE
Site-setting scope holding the theme’s site name, tagline and footer.

Functions§

apply
Apply a starter theme to one site (a tenant pool), once. Its sample pictures are left out; see apply_with_media.
apply_with_media
apply, storing the theme’s sample pictures in the site’s media library first. files are (file name, bytes) for the media entries; org_slug is the site whose media storage they go to.
parse
Parse and check a theme.json without touching a database: every schema valid, every page of a declared type, every menu link resolving.