Relatude.CMS#

A practical manual

Relatude.CMS is the content layer on top of Relatude.DB, the open-source object-oriented graph database for .NET. It ships as the NuGet package Relatude.DB.CMS and gives a web application a content model (items, pages, templates, sites, users), a pluggable way to render pages with MVC views, controllers, Razor Pages or any IResult, CMS settings, privacy-safe page-view analytics, fast HTML utilities, a donations model, and an API with a TypeScript SDK for the CMS interface editors work in and the plugins that extend it.

This manual covers what the CMS adds. The database itself (modelling, writing, querying, URLs, files, logs) is covered by the Relatude.DB manual, and is linked where it matters.

Version note. Relatude.CMS is pre-1.0 and targets .NET 10. Everything here is taken from the source in Relatude.CMS/. When something here disagrees with your build, the source wins.

Part I — Setting up#

1. What Relatude.CMS is#

Relatude.CMS is a class library with no entry point. A host ASP.NET Core application starts Relatude.DB, adds the CMS, owns the schema through the admin UI at /relatude.db, and decides how pages look. The CMS supplies the parts every content site needs and leaves the rest to the host.

Two packages build on it: Relatude.DB.Ecom (products, orders, carts, pricing) and Relatude.DB.Marketing (newsletters and deliveries). Each has its own README.

Content types are C# interfaces. Relatude.DB generates the implementing classes, so a site declares IArticle : IPage and never writes the class. Relations between nodes are small marker classes, and every read and write goes through a NodeStore. The Relatude.DB manual explains all three in depth; this manual assumes them.

2. Setting up the host#

The smallest setup#

Six lines in Program.cs make a working CMS host:

var builder = WebApplication.CreateBuilder(args);
builder.AddRelatudeCMS().AddMvcRendering();

var app = builder.Build();
app.UseRelatudeCMS();
app.MapRelatudeCMS();
app.Run();

The calls are in the global namespace, so Program.cs needs no using for them.

What the defaults give you#

Started like this, the site:

• keeps its database in relatude.data/ and its settings in relatude.settings/relatude.db.json, both in the project folder, and creates them on the first start;
• serves the admin UI at /relatude.db;
• gives a page with the address hello-world the URL /hello-world, and serves nothing at / until it has a home page (chapter 6);
• sends stored files, such as images and video, at the URLs db.GetUrl(file) makes;
• leaves every URL the database does not know to the rest of the application, which ends in a 404;
• records no page views until analytics is turned on in the admin UI.

A first page#

What the setup does not know yet is your content. A page takes three more pieces: a content type, its registration, and something to render it.

// Models/IArticle.cs: a content type is an interface, and Relatude.DB writes the class
using Relatude.CMS.Models;
using Relatude.DB.Nodes;

namespace MySite.Models;

public interface IArticle : IPage {
    [HtmlProperty] string Body { get; set; }
}

// Program.cs: the smallest setup, with the content type registered and rendered
using MySite.Models;
using Relatude.DB.Datamodels;

var builder = WebApplication.CreateBuilder(args);
builder.AddRelatudeDB(o => o.OnDatamodelInit = (dm, _) => {
    dm.AddCmsContentModel();      // IItem, IPage and the templates
    dm.Add<IArticle>();           // the site's own types
});
builder.AddRelatudeCMS()
    .AddMvcRendering()
    .AddRendering(o => o.RenderRazorView<IArticle>());   // every article renders with the view "Article"

@* Views/Shared/Article.cshtml *@
@using MySite.Models
@model IArticle
<h1>@Model.Name</h1>
@Html.Raw(Model.Body)

An article needs an address to have a URL. Here the site creates one the first time it starts:

builder.AddRelatudeDB(o => o.OnStoreOpenBackground = db => {
    if (db.Query<IArticle>().Count() > 0) return;
    var article = db.CreateAndInsert<IArticle>(a => { a.Name = "Hello world"; a.Body = "<p>It works.</p>"; });
    db.UpdateAddress(article.Id, "hello-world");
});

GET /hello-world now renders Views/Shared/Article.cshtml with the article as its model. The second AddRelatudeDB call is not a mistake: every call configures the same options.

The options#

Each option below is something added to the smallest setup. None of them has to come in a particular order.

Configuring the database#

AddRelatudeCMS() adds Relatude.DB with its defaults. Call AddRelatudeDB(o => …) yourself, before or after it and as often as you like, to configure it.

The Relatude.DB manual lists the rest in Options and events in Program.cs.

Registering content types#

Content types are registered in code, as above, or as datamodel sources in the admin UI. Both add up: the sources load first, then OnDatamodelInit runs. A source names a namespace, and matching is exact, so every namespace with node types is a source of its own:

"DatamodelSources": [
  { "Id": "<unique guid>", "Name": "CMS",       "Namespace": "Relatude.CMS.Models",           "Type": "AssemblyNameReference", "Reference": "Relatude.DB.CMS" },
  { "Id": "<unique guid>", "Name": "My site",   "Namespace": "MySite.Models",                 "Type": "AssemblyNameReference", "Reference": null },
  { "Id": "<unique guid>", "Name": "Donations", "Namespace": "Relatude.CMS.Models.Donations", "Type": "AssemblyNameReference", "Reference": "Relatude.DB.CMS" }
]

• Every source needs its own unique Id; the store refuses to start without one.
• A base interface whose namespace is not registered silently drops its members from every type derived from it.
• In code, dm.AddCmsContentModel() adds IItem, IPage, ITemplate and the template kinds, and dm.AddNamespace<IArticle>() adds every type in the site's own namespace. dm.AddNamespace<IItem>() would add the CMS's users, groups and sites too, which build on Relatude.DB's own system types and fail without them.

Choosing how pages render#

Add the rendering systems a site uses, one call each:

builder.AddRelatudeCMS().AddMvcRendering();                          // views and controllers
builder.AddRelatudeCMS().AddRazorPagesRendering();                   // Razor Pages
builder.AddRelatudeCMS();                                            // no rendering: files, JSON and GetContent<T>() still work

A host's own AddControllersWithViews(o => …) or AddRazorPages() works beside these. They add to the same MVC, so its filters and options apply to content requests too.

The request pipeline#

The smallest setup leaves the order of the middleware to ASP.NET Core. A real site adds static files, its own routes and a fallback, and this is the order that works:

var app = builder.Build();

app.UseRelatudeCMS();                        // the database first: while it opens, requests get a progress page
app.UseStaticFiles();                        // wwwroot, before routing...
app.UseRouting();                            // ...so a request for a static file never looks for content
app.UseAuthentication();                     // what runs after UseRouting runs for pages too
app.UseAuthorization();

app.MapGet("/api/status", () => "ok");       // explicit routes win over content
app.MapRelatudeCMS();                    // pages and stored files
app.MapFallback(() => Results.NotFound());   // what neither answers

app.Run();

UseRelatudeCMS() calls UseRelatudeDB(), so a host that calls both starts the database once.

Who the visitor is#

Authentication is ASP.NET Core's: cookies, Identity, OpenID Connect, whichever the site uses. The CMS needs one thing from it, which user node the signed-in visitor is, and the store does the rest: every read as that visitor honours the read access editors set on pages, by group, in the admin UI.

sign-in (the host's)
      │
      ▼
ClaimsPrincipal ──► the CMS: which ICMSUser is this? ──► the store reads as that user:
                    the NameIdentifier claim is the node's id,   read access by group,
                    else the Email claim finds the node          published content only

Sign a user in with CmsPrincipal.For, which writes the id the CMS reads back, with the user's name, email and groups as roles:

app.MapPost("/login", async (RelatudeCmsContext ctx, string email, string password) => {
    var user = Members.Verify(ctx.Admin, email, password);     // the site's own password check
    if (user == null) return Results.Unauthorized();
    await ctx.Http.SignInAsync(CmsPrincipal.For(user, CookieAuthenticationDefaults.AuthenticationScheme));
    return Results.Redirect("/");
});

[Authorize(Roles = "Editors")] then works on the site's own controllers, with the names of the user's groups as roles. Users are ICMSUser nodes and groups ICmsUserGroup nodes, which need the engine's user model in the datamodel: dm.AddNamespace<ISystemUser>(), then dm.Add<ICMSUser>() and dm.Add<ICmsUserGroup>().

A page the visitor may not read sends an anonymous visitor to the login page and answers a signed-in one with 403 (chapter 7). AddRelatudeCMS(o => …) sets the three things that differ between sites:

builder.AddRelatudeCMS(o => o.Culture = ctx => ctx.Http.Request.Host.Host.EndsWith(".no") ? "nb-NO" : "en-GB");

Website2 has all of it running: members with passwords, a cookie sign-in, articles for a group only, and an open page to set members, groups and access, so the rules can be tried out.

Using the database in code#

NodeStore (namespace Relatude.DB.Nodes) is the whole data API. In a request, RelatudeCmsContext (namespace Relatude.DB.CMS.Web) hands out the store and knows the request; code with no request reads through IRelatudeDBAccessor:

public class NewsController(RelatudeCmsContext ctx) : Controller {
    public IActionResult Index() => View(ctx.Db.Query<IArticle>().Page(0, 10).Execute());
}

@inject RelatudeCmsContext Ctx
@foreach (var article in Ctx.Db.Query<IArticle>().Page(0, 5).Execute()) {
    <a href="@Ctx.GetUrl(article)">@article.Name</a>
}

// a hosted service can start before the database: IsOpen is false, never an exception, until it is open
public class Warmup(IRelatudeDBAccessor db) : BackgroundService {
    protected override async Task ExecuteAsync(CancellationToken stop) {
        while (!db.IsOpen) await Task.Delay(500, stop);
        var articles = db.Database.Query<IArticle>().Count();
    }
}

One per request, and each part is worked out on first use, so a view that never asks for the user never looks it up. Content routing reads through it, as the visitor (chapter 7). Methods that write data take the NodeStore db as a parameter rather than capturing one.

Hooking in from a library#

A library registers its transaction plugins and task runners with an IStoreInitializer service (namespace Relatude.DB.NodeServer) rather than with OnStoreInit, which belongs to the host and which a later assignment would replace. The server calls every one for each store before it opens:

public sealed class AuditInitializer : IStoreInitializer {
    public void Initialize(NodeStore store) => store.RegisterTransactionPlugin(new AuditPlugin());
}

services.TryAddEnumerable(ServiceDescriptor.Singleton<IStoreInitializer, AuditInitializer>());

The CMS registers its own save checks this way. Two more services cover the other moments a library needs: an IDatamodelInitializer adds its model types to every datamodel, after OnDatamodelInit, and an IStoreOpenHandler seeds data or starts work once a store is open, on a background thread. A CMS module is all of this, and more, described in one class (chapter 18).

What AddRelatudeCMS registers#

Replace a service by registering your own, before or after AddRelatudeCMS(), the way a preview resolver replaces ContentResolver (chapter 7).

Everything together#

Website2 in the repository puts the options together: a page tree with a home page at /, code defaults for every page type, templates for articles, a selector, and the pipeline above. Its Program.cs, shortened:

using Relatude.CMS.Models;
using Relatude.DB.CMS.Web.Rendering;
using Relatude.DB.Web;

var builder = WebApplication.CreateBuilder(args);

builder.AddRelatudeDB(o => {
    o.OnDatamodelInit = (dm, _) => {
        dm.AddCmsContentModel();
        dm.AddNamespace<ISitePage>();                // the page types and the PageTree relation
    };
    o.CreateUrlManager = _ => new DefaultUrlManager(new DefaultUrlManagerOptions {
        Parents = [new UrlParentRelation { ParentRelationName = nameof(PageTree) }],   // /products/bikes/trail-one
        FallbackRootId = SiteSeeder.HomeId,          // the home page at "/"
    });
    o.OnStoreOpenBackground = SiteSeeder.SeedIfEmpty;
});

builder.AddRelatudeCMS()
    .AddMvcRendering().AddRazorPagesRendering()
    .AddRendering(o => o
        .Select((http, m) => http.Request.Query["format"] == "json" ? new ResultTarget((_, c) => Results.Json(new { c.Content.Name })) : null)
        .RenderRazorView<IHomePage>("Home")
        .RenderMvcController<ISectionPage>("Section")
        .RenderRazorView<IProductPage>(p => p.InStock ? "Product" : "ProductSoldOut")
        .RenderRazorPage<ILandingPage>("Landing")
        .RenderRazorView<IPage>("Default"));              // any other page

var app = builder.Build();

app.UseRelatudeCMS();
app.UseStaticFiles();
app.UseRouting();
app.MapRelatudeCMS();
app.MapFallback(() => Results.NotFound("No page here."));

app.Run();

Its README lists the URLs to try. Chapter 24 goes further and puts every option in one Program.cs.

Part II — The content model#

3. Content types#

Every CMS node is an IItem. Routable content is an IPage.

public interface IItem {
    Guid Id { get; set; }
    [StringProperty(Indexed = true)] string Name { get; set; }
    NodeMeta Meta { get; }                     // created, changed, culture, address (Meta.Address)…
}

public interface IPage : IItem {
    string MetaTitle { get; set; }
    string MetaDescription { get; set; }
    string MetaKeywords { get; set; }
    bool ShowInMenu { get; set; }
    bool ShowInTree { get; set; }
    Reference<ITemplate> Template { get; set; }     // the page's template, or none
}

A site declares its own content types on top of them:

using Relatude.CMS.Models;

namespace MySite.Models;

public interface IArticle : IPage {
    string Intro { get; set; }
    string Body { get; set; }
}

public interface INewsList : IPage {
    int PageSize { get; set; }
}

public interface ILandingPage : IPage {
    string Headline { get; set; }
}

Creating, reading and changing them is plain Relatude.DB:

var article = db.Create<IArticle>();     // not stored yet
article.Name = "Hello world";
article.Intro = "The first article.";
db.Insert(article);

var loaded = db.Get<IArticle>(article.Id);
loaded.Intro = "Changed.";
db.Update(loaded);                       // a changed node is stored only by Update

var latest = db.Query<IArticle>().OrderByMetaDescending(m => m.CreatedUtc).Take(10).Execute();

Template is a Reference<ITemplate>: read it with .TryGet() and .IsSet(), and set it with .Set(id) before the page is saved. Relation ends, such as the Parent and Children of a page tree, are objects too; change them with db.SetRelation, AddRelation, RemoveRelation and ClearRelation, never by assignment.

4. The other base types#

On ICMSUser, Email and Mobile are unique when not empty, and CultureCode holds the user's preferred culture, such as nb-NO, or nothing. Name is a stored, indexed property on purpose, not a display-name marker.

ICountry sits in the namespace Relatude.CMS, not Relatude.CMS.Models. A site that uses it registers that namespace as a datamodel source too.

5. Templates#

A template is a layout an editor can choose for a page. Where every page of a type looks the same, no template is needed: code says what renders the type (chapter 8). Where editors choose, say between a standard and a wide article layout, each choice is a template, and the page points at the one it uses:

the page                        the template                      the code
"Hello world", an IArticle      "Article, wide"
  Template ──────────────────►    ViewName  = "ArticleWide" ────►  Views/Shared/ArticleWide.cshtml,
                                  NodeTypes = [IArticle]            rendered with the page as its model

Templates are nodes, created in the admin UI like other content. Each has:

Editors create templates in the admin UI. The same in code:

Guid typeOf<T>() => db.Datastore.Datamodel.NodeTypesByFullName[typeof(T).FullName!].Id;

var wide = db.CreateAndInsert<IRazorViewTemplate>(t => {
    t.Name = "Article, wide";
    t.ViewName = "ArticleWide";
    t.NodeTypes = [typeOf<IArticle>()];
});

var article = db.CreateAndInsert<IArticle>(p => {
    p.Name = "Hello world";
    p.Template.Set(wide.Id);
});

Two things to know:

• A view name in a template ties content to code. Rename ArticleWide.cshtml and every template naming it breaks. The startup check logs every name that no longer exists (chapter 8).
• NodeTypes holds type ids. The CMS's own types have fixed ids. Give the site's types one too, with [Node(Id = "…")] on the interface, since a type without one gets its id from its name, and renaming IArticle would leave every template listing it pointing at nothing.

Part III — URLs#

6. Addresses and URLs#

A URL is never stored. A page has an address, one segment such as hello-world, and the store's URL manager builds the URL from it. The same manager turns a requested URL back into the page, so the two directions always agree.

The default: one address, one URL#

var article = db.CreateAndInsert<IArticle>(a => a.Name = "Hello world");
db.UpdateAddress(article.Id, "hello-world");

db.GetUrl(article);                    // "/hello-world"

A request for /hello-world now reaches the article (chapter 7). With nothing configured:

• every page answers at /{address}, and a page without an address has no URL;
• an address is unique across the site: a second hello-world is saved as hello-world-2;
• / addresses nothing until the site has a home page, a root (below).

Good addresses#

Slugs. The store keeps only plain ASCII in an address. RelatudeUrlHelper.ToUrlSlug (namespace Relatude.CMS.Engine.Web) makes a readable one from a name first: lower case, æ, ø and å transliterated, other accents removed, everything else turned into single dashes, and node when nothing is left.

RelatudeUrlHelper.ToUrlSlug("Blåbær og Øl");   // "blabaer-og-ol"
RelatudeUrlHelper.ToUrlSlug("Café Crème!");    // "cafe-creme"

Collisions are the store's job. When an address would give two pages the same URL, it appends -2, -3 and so on as the transaction commits, so code that sets addresses never checks for them. Read the address back if you need it.

Editors set a page's address when its type has a property marked [AddressProperty]. The property is the address, so editing it in the admin UI moves the page:

public interface IArticle : IPage {
    [AddressProperty] string Slug { get; set; }
    [HtmlProperty] string Body { get; set; }
}

Automatically, a transaction plugin gives every new page an address from its name:

using Relatude.CMS.Engine.Web;
using Relatude.CMS.Models;
using Relatude.DB.Common;
using Relatude.DB.Nodes;
using Relatude.DB.Transactions;

public class PageAddressPlugin : NodeTransactionPlugin<IPage> {
    public override void OnBeforeNodeAction(NodeKey key, NodeOperation operation, Transaction transaction, NodeHelper<IPage> helper) {
        if (operation is NodeOperation.InsertOrFail or NodeOperation.InsertIfNotExists
            && helper.GetProperty(p => p.Name) is string name) {
            transaction.UpdateAddress(key.Guid, RelatudeUrlHelper.ToUrlSlug(name));
        }
        base.OnBeforeNodeAction(key, operation, transaction, helper);
    }
}

// Program.cs
builder.AddRelatudeDB(o => o.OnStoreInit = db => db.RegisterTransactionPlugin(new PageAddressPlugin()));

It acts on inserts only (db.Insert is InsertOrFail). Adding the update operations would move a page's URL whenever it is renamed, breaking links to it. Relatude.Ecom's ShopTemplateSetterPlugin does the same for products, on updates as well.

The options#

Everything else is an option of the URL manager. Set the options in the database's settings, in the admin UI or in relatude.db.json under LocalSettings.UrlOptions:

"UrlOptions": {
  "FallbackRootId": "7e1a0001-5eed-4c0d-9a11-000000000001",
  "Parents": [ { "ParentRelationName": "PageTree" } ]
}

or in code, where a manager made by CreateUrlManager replaces the settings file's options entirely:

using Relatude.DB.Web;

builder.AddRelatudeDB(o => o.CreateUrlManager = _ => new DefaultUrlManager(new DefaultUrlManagerOptions {
    FallbackRootId = HomeId,
    Parents = [new UrlParentRelation { ParentRelationName = "PageTree" }],
}));

The sections below take the options one at a time, each with what it does to the URLs.

A home page at /#

FallbackRootId makes a page the site's root. The root answers /, so it is the home page:

new DefaultUrlManagerOptions { FallbackRootId = HomeId }

/              the home page
/hello-world   the article, as before

The root is chosen by id, so create the home page with a fixed one:

public static readonly Guid HomeId = new("7e1a0001-5eed-4c0d-9a11-000000000001");

db.CreateAndInsert<IHomePage>(p => p.Name = "Home", new NodeKey(HomeId));

Page trees: /products/bikes/trail-one#

Parents names the relation that leads from a page to its parent. A page's URL is then its ancestors' addresses followed by its own, below the root:

public interface ISitePage : IPage {
    PageTree.Parent Parent { get; set; }
    PageTree.Children Children { get; set; }
}

public class PageTree : OneToMany<ISitePage, ISitePage> {
    public class Parent : One { }
    public class Children : Many { }
}

new DefaultUrlManagerOptions {
    FallbackRootId = HomeId,
    Parents = [new UrlParentRelation { ParentRelationName = nameof(PageTree) }],
}

Home (the root)            /
├─ Products                /products
│  └─ Bikes                /products/bikes
│     └─ Trail One         /products/bikes/trail-one
└─ News                    /news
   └─ Bikes                /news/bikes

• An address only has to be unique among siblings. Both bikes pages above are fine.
• Nothing about the path is stored. Moving a page, or renaming a section, changes every URL below it on the next read.
• The root's own address is not part of the URLs. /products, not /home/products.
• Several relations can lead to a parent, such as pages under pages and documents under pages. List them in Parents, in priority order.

Relations are set with db.AddRelation, before the child's address, so the store checks the address against the right siblings:

db.AddRelation<ISitePage>(products.Id, p => p.Children, bikes.Id);
db.UpdateAddress(bikes.Id, "bikes");

Several sites, one per domain#

Domains gives each host a root. A host serves the pages below its root, and the root answers /:

new DefaultUrlManagerOptions {
    Parents = [new UrlParentRelation { ParentRelationName = nameof(PageTree) }],
    Domains = [
        new UrlDomain { Host = "www.bikes.no", RootId = bikesHome },
        new UrlDomain { Host = "www.skis.no", RootId = skisHome },
    ],
    FallbackRootId = bikesHome,   // localhost, staging and any other host
}

https://www.bikes.no/products   the products page below bikesHome
https://www.skis.no/products    the products page below skisHome
http://localhost:5000/products  the fallback root's: bikesHome

Nothing about the domain is stored on a page, so the same database runs locally unchanged. db.GetUrl(page, absolute: true) adds the host of the page's domain, https://www.skis.no/products; without domains there is no host to add, and the URL stays relative.

A base path and trailing slashes#

new DefaultUrlManagerOptions { PrimaryBaseAddress = "/site", IncludeTrailingSlash = true }

/site/products/bikes/    a page URL starts with /site, and ends with a slash
/site/assets/…           a file URL starts with /site too

BaseAddressPages and BaseAddressAssets prefix only page URLs or only file URLs, after the primary base. A base with a scheme and host, such as https://cdn.example.com for files, makes those URLs absolute. Inbound URLs match either way.

URLs that survive a rename#

UrlFormat can put a page's id in its URL. With EncodedGuidAndAddress, the id finds the page and the address is only there to be read:

OnlyAddress (the default)    /products/bikes/trail-one
EncodedGuidAndAddress        /PSobnF9OcWCCk6S1xtfo-Q/products/bikes/trail-one

The second keeps working when the page is renamed or moved, and addresses never need a -2. The Relatude.DB manual lists all ten formats.

File URLs#

Stored files have URLs of their own, made by db.GetUrl(file) and db.GetUrl(file, adjustment):

/assets/{token}/trail-one.jpg     the file as it was uploaded
/assets/{token}/trail-one.webp    a variant, such as a resized image

The token says which file and which variant; the file name at the end is only for downloads. The options move them (AssetUrlRoot, BaseAddressAssets for a CDN), make them readable (PropertyPathFormat, AssetUrlFormat), or sign them so that an edited URL stops working (AssetUrlSignatureKey). See Asset URLs in the Relatude.DB manual. Chapter 7 tells how they are served.

All the options#

URLs and the URL manager in the Relatude.DB manual covers each in depth, and how to write a URL manager of your own.

Links in rich text#

A link in an [HtmlProperty] survives the rename of the page it points to. The store keeps it by id and writes the current URL into every read, so editors paste ordinary URLs and never fix them later.

7. Answering a request#

The default#

app.MapRelatudeCMS() is all it takes. For a request that no other route answers, it asks the URL manager what the URL addresses, once, and answers by what it finds:

GET /products/bikes/trail-one
       │
       ▼
  the URL manager: what does this URL address?
       │
       ├── a page ──────────────────────►  rendered; a page nothing renders falls through
       ├── a stored file ───────────────►  sent, with range requests and caching
       ├── a page or file the visitor ──►  a login redirect, or 403 once signed in
       │   may not read
       └── nothing ─────────────────────►  the request goes on: other routes, MapFallback, or a 404

How a page is rendered is Part IV; how a file is sent is below.

With the article from chapter 6:

GET /hello-world                  Views/Shared/Article.cshtml, with the article as its model
GET /assets/{token}/photo.jpg     the photo
GET /no-such-page                 MapFallback, or a 404

Content is read as the visitor: anonymous, or the signed-in user (chapter 2). An unpublished page is answered as if it did not exist. A page or file that exists but the visitor may not read sends an anonymous visitor to the login page and answers a signed-in one with 403, or the scheme's access denied page; with LoginRedirect off, it too is answered as if it did not exist.

Which route wins#

• Explicit routes win. The content routes are catch-alls on {**url}, the lowest precedence, so app.MapGet("/search", …) answers /search even when a page has the address search.
• Static files come first when UseStaticFiles() runs before UseRouting(): a request for /css/site.css never asks the database.
• Everything else falls through to the host's other routes, MapFallback, or a 404.
• While the database opens, Relatude.DB answers every request with a progress page.

Stored files#

Images, video and downloads are served by the same routes as pages, from the URL taken apart once. The answer comes from Relatude.DB's FileHandler:

@inject RelatudeCmsContext Ctx
<img src="@Ctx.GetUrl(Model.Picture)" alt="">
<img src="@Ctx.GetUrl(Model.Picture, new FileAdjustmentImage { Width = 400 })" alt="">
<video src="@Ctx.GetUrl(Model.Film)" controls></video>

• Variants, such as a resized image or a converted video, are made on first request. A browser waits for them, so they go ahead of conversions running in the background.
• Range requests get 206 Partial Content, which video and audio players need to seek. A file kept on local disk is read straight from it; one on blob storage is sent whole.
• Caching. A finished variant may be cached for 30 days, and its URL changes when the file does. A variant still being converted is not cached.
• Read as the visitor. A file on a page the visitor may not read gets the same login redirect as the page.

Options#

A part of the site only#

MapRelatudeCMS takes a route pattern. Together with a base path for the URLs, the database answers below /site and the rest of the application keeps every other path:

builder.AddRelatudeDB(o => o.CreateUrlManager = _ => new DefaultUrlManager(new DefaultUrlManagerOptions { PrimaryBaseAddress = "/site" }));

app.MapRelatudeCMS("site/{**url}");

Finding content another way#

ContentResolver.Resolve is the one place a URL becomes content. Override it to find content another way, such as preview links or a legacy URL scheme. base.Resolve keeps the default, and Match(node) gives any node its template or code default, as a URL would:

using Relatude.CMS.Engine;
using Relatude.CMS.Models;
using Relatude.DB.CMS.Web.Rendering;

// ?preview=<page id> shows any page to editors; everything else resolves by URL
public sealed class PreviewContentResolver(IRelatudeDBAccessor db, ContentRenderingOptions options)
    : ContentResolver(db, options) {

    protected override ContentMatch? Resolve(HttpRequest request) {
        if (request.HttpContext.User.IsInRole("Editor")
            && Guid.TryParse(request.Query["preview"].ToString(), out var id)
            && Context(request.HttpContext).Admin.TryGet<IPage>(id, out var page)) {
            return Match(page);
        }
        return base.Resolve(request);
    }
}

// Program.cs, before or after AddRelatudeCMS()
builder.Services.AddSingleton<ContentResolver, PreviewContentResolver>();

ContentResolver is a singleton. Its answer for a request lives on the HttpContext, so an override keeps no state of its own. Context(http) is the request's RelatudeCmsContext: its Url is the URL taken apart, Node the node read as the visitor, and Db the store to read more with.

Another router beside it#

A host that also routes a legacy CMS maps its own transformer beside MapRelatudeCMS(). It answers only what the database does not address, so content, files included, always comes first and the two never answer the same URL:

using Microsoft.AspNetCore.Mvc.Routing;
using Relatude.DB.CMS.Web.Rendering;

public sealed class LegacyRouting(ContentResolver content, LegacyRouter legacy) : DynamicRouteValueTransformer {
    public override ValueTask<RouteValueDictionary> TransformAsync(HttpContext http, RouteValueDictionary values) {
        var ours = content.GetContent(http) != null || content.GetFile(http) != null;
        return ValueTask.FromResult(!ours && legacy.TryRoute(http, values) ? values : null!);   // null: no match
    }
}

// Program.cs
builder.AddRelatudeCMS().AddMvcRendering();
builder.Services.AddScoped<LegacyRouting>();
app.MapRelatudeCMS();
app.MapDynamicControllerRoute<LegacyRouting>("{**url}");

MvcContentRouteTransformer.TrySetRouteValues sets the route values for MVC targets, for a host that builds its routing from scratch instead.

Part IV — Rendering content#

8. What renders a page#

Two things can say what renders a page: code, once per page type, or a template the editor chose for the page. A site can use either or both. Code is the simplest, one line per type and nothing in the database. Templates are for the pages where editors choose between layouts.

GET /news/hello-world
       │
       ▼
  the page: an IArticle
       │
       ├── has the editor chosen a template? ───────────── yes ──►  what the template says:
       │                                                            a view, a controller, a Razor Page
       │ no
       ├── is there a template made for IArticle? ──────── yes ──►  that template
       │ no
       ├── is there a code default for IArticle? ────────── yes ──►  RenderRazorView<IArticle>():
       │                                                            Views/Shared/Article.cshtml
       │ no
       ▼
  not rendered: the request goes on to MapFallback, or a 404

Code decides: code defaults#

A code default says what renders every page of a type that has no template:

builder.AddRelatudeCMS()
    .AddMvcRendering().AddRazorPagesRendering()
    .AddRendering(o => o
        .RenderRazorView<IHomePage>("Home")             // Views/Shared/Home.cshtml
        .RenderRazorView<IArticle>()                    // no name: the type's, so Views/Shared/Article.cshtml
        .RenderMvcController<ISectionPage>("Section")   // SectionController.Index
        .RenderRazorPage<ILandingPage>("Landing")       // Pages/Landing.cshtml
        .RenderRazorView<IPage>("Default"));            // every other page

A default covers its type and every type derived from it, and the closest type wins:

IPage ◄── IArticle ◄── INews        RenderRazorView<IPage>("Default")
                                    RenderRazorView<IArticle>()

an INews     → "Article"     IArticle is one step up, IPage two
an IProduct  → "Default"     only the IPage default covers it

Defining a default for the same type again replaces the first. Code defaults work for any content type, not only pages.

ViewPerType() is a shortcut for sites where every type has a view named after it: content nothing else renders gets that view, so an IFaqPage renders with FaqPage. It is off by default.

Editors decide: templates#

Templates need no setup:

• a template renders by its kind: a view template renders its view, a controller template its action, a Razor Page template its page (chapter 5);
• a page without a template gets the template made for its type: the one whose NodeTypes is closest to the page's type, the same way code defaults are chosen.

So templates work without any code, when the site's pages all look alike per type. Where editors are meant to choose, make more than one template for the type. A page then has to choose, since none of them is closer than the others:

templates "article" and "article-wide", both for IArticle

an IArticle with Template = "article-wide"   → ArticleWide.cshtml
an IArticle with Template = "article"        → Article.cshtml
an IArticle with no template                 → error: both fit it equally, so the page has to choose

Saving a page without a template is refused in that case, so editors see the problem in the admin UI, not visitors on the site.

Both together#

A page's own template always wins, as long as it is for the page's type. Otherwise the closest template or code default wins, with two tie rules:

• A template as close as a code default wins over it. Editors can take over a type by making a template for it, with no change to the code.
• A template for no types comes last, after every code default. It is the layout for whatever nothing else covers.

IPage ◄── IArticle ◄── INews        code:       RenderRazorView<IArticle>()      for IArticle
                                    templates:  "news"                           for INews
                                                "fallback"                       for no type

an INews     → template "news"        the closest
an IArticle  → RenderRazorView        the only one for IArticle itself
an IProduct  → template "fallback"    nothing closer; a template for no type is last
                                      (with RenderRazorView<IPage>("Default") added: "Default")

Deciding per request: selectors#

A selector looks at the request before anything else, for every page. The first selector to answer wins, and null passes the page on:

.AddRendering(o => o
    .Select((http, m) => http.Request.Query["view"] == "print" && m.Content is IArticle ? new RazorViewTarget("ArticlePrint") : null)
    .Select((http, m) => http.Request.Query["format"] == "json" ? new ResultTarget((_, c) => Results.Json(new { c.Content.Name })) : null))

Print views, previews, A/B tests and a theme per site all start here. A selector that needs a service takes it from http.RequestServices.

A selector is also how code overrides a template, since a page with a template otherwise renders by its kind, and how a plain ITemplate renders at all. It tells templates apart by their name or id:

.AddRendering(o => o
    // every page with the template "campaign": a Blazor component
    .Select((http, m) => m.Template?.Name == "Campaign"
        ? new ResultTarget((_, c) => new RazorComponentResult<CampaignPage>(new { Content = c.Content }))
        : null)
    // per page: a long article gets another view; null leaves the page to its template
    .Select((http, m) => m.Template?.Name == "Article" && m.Content is IArticle { Body.Length: > 20_000 } ? new RazorViewTarget("ArticleLong") : null))

A name is what editors see, and they may change it. A template that renders the same way for every page is sturdier as a kind of its own, below, since editors then see what renders it.

A template kind of your own#

A site adds a kind of template, which editors create in the admin UI like the built-in ones, by deriving from ITemplate and saying what renders it:

public interface IJsonTemplate : ITemplate {
    string Fields { get; set; }
}

.AddRendering(o => o.TemplateKind<IJsonTemplate>(t =>
    new ResultTarget((http, m) => Results.Json(new { m.Content.Id, m.Content.Name, fields = t.Fields }))))

The whole order#

the request
   │
   ├─ 1. selectors, in the order added ─────────────── the first answer wins
   │
   ├─ 2. the page has a template:
   │        the template's kind ─────────────────────── your own kinds first, then the built-in ones
   │
   ├─ 3. the page has no template:
   │        the code default for the closest type ───── an answer wins, null passes on
   │        ViewPerType(): the view named after the type
   │
   └─ 4. nothing: the page is not rendered

Step 2 and step 3 never both apply: a page with a template is rendered by it, a page without one by code. Which template a page gets, when it chose none, is settled before this, by the rules above.

Mistakes are caught early#

A wrong setup is found before a visitor sees it: when an editor saves a page, and in the log when the site starts and whenever a template changes.

A code default decided per page names nothing up front, so the log cannot check it.

The targets#

What every decision above ends in: a target, which names the code that renders the page.

The Render… shorthands and the template kinds make these for you; a selector returns one itself. A target whose rendering system was not added is not rendered.

9. MVC views and controllers#

Views#

A view renders the page directly, with the page as its model and no controller of your own. It is found the MVC way: by name in Views/Shared, or by a full path such as ~/Views/Pages/Article.cshtml.

@* Views/Shared/Article.cshtml, from RenderRazorView<IArticle>() or a view template *@
@using MySite.Models
@model IArticle

<article>
    <h1>@Model.Name</h1>
    <p class="intro">@Model.Intro</p>
    @Html.Raw(Model.Body)
</article>

Controllers#

A controller is for pages that need more than a view: query parameters, a model built from several queries, a form. The action gets the page through [FromContent]; other parameters bind as usual.

using Microsoft.AspNetCore.Mvc;
using MySite.Models;
using Relatude.DB.CMS.Web;
using Relatude.DB.CMS.Web.Rendering;

// from RenderMvcController<INewsList>("News") or a controller template
public class NewsController(RelatudeCmsContext ctx) : Controller {
    public IActionResult Index([FromContent] INewsList list, int page = 0) {
        var articles = ctx.Db.Query<IArticle>().Page(page, list.PageSize).Execute();
        return View(new NewsListModel(list, [.. articles], articles.TotalCount));
    }
}

public record NewsListModel(INewsList List, IArticle[] Articles, int TotalCount);

The controller is reached through the page's URL, not its own, so it has no [Route] and no [ApiController]: those make an action unreachable this way.

10. Razor Pages#

A Razor Page is named by its path below Pages/. Its handler gets the page through [FromContent], and the @page directive needs no route of its own.

// Pages/Landing.cshtml.cs, from RenderRazorPage<ILandingPage>("Landing") or a Razor Page template
using Microsoft.AspNetCore.Mvc.RazorPages;
using MySite.Models;
using Relatude.DB.CMS.Web.Rendering;

public class LandingModel : PageModel {
    public ILandingPage? Landing { get; private set; }

    public void OnGet([FromContent] ILandingPage? page) => Landing = page;
}

@* Pages/Landing.cshtml *@
@page
@model LandingModel

<h1>@Model.Landing?.Headline</h1>

11. Any IResult: Blazor, JSON and the rest#

A ResultTarget returns any IResult, so it needs neither MVC nor Razor Pages: JSON for a headless client, a file, a template engine of your own, or a Blazor component rendered on the server.

builder.AddRelatudeCMS()
    .AddRendering(o => o
        // JSON for a headless client: a projection, never the node itself
        .RenderResult<IApiPage>((http, page) => Results.Json(new { page.Id, page.Name }))
        // RSS, through a class of the site's own
        .RenderResult<IFeedPage>((http, feed) => Results.Text(FeedWriter.Rss(feed), "application/rss+xml")));

Serialize a projection, never the node itself. A node's relations are enumerable, so a serializer handed the node would walk into every related node, and on through theirs.

Blazor#

A Blazor component renders a page through RazorComponentResult. The component is a plain one, with no @page, and receives the page through a parameter named Content:

@* Components/ArticlePage.razor *@
@using MySite.Models
<PageTitle>@Content.Name</PageTitle>
<h1>@Content.Name</h1>
@((MarkupString)Content.Body)
<LikeButton ArticleId="@Content.Id" @rendermode="InteractiveServer" />

@code {
    [Parameter] public IArticle Content { get; set; } = default!;
}

using Microsoft.AspNetCore.Http.HttpResults;   // RazorComponentResult

builder.Services.AddRazorComponents().AddInteractiveServerComponents();

builder.AddRelatudeCMS()
    .AddRendering(o => o
        .RenderResult<IArticle>((http, article) => new RazorComponentResult<ArticlePage>(new { Content = article })));

app.UseAntiforgery();                           // MapRazorComponents needs it, even for static pages
app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
app.MapRelatudeCMS();

Two rules keep this working, now and when Blazor becomes a rendering system of its own, with a template kind and a RenderRazorComponent shorthand beside the view, controller and Razor Page ones:

• Content pages render statically, with interactive islands inside them. The page is found from the request, which exists only while the component renders on the server. Interactive parts go in child components with their own @rendermode, like LikeButton above.
• Never pass a node into an interactive component. Its parameters are serialized to the browser or the circuit, and a node's relations would pull in every related node. Pass an id or a small projection; the component reads what it needs through RelatudeCmsContext.Db, or its own service.

RazorComponentResult renders the component as a whole document, outside the host's App.razor, Routes.razor and layout, so the component, or a layout component it wraps itself in, has to produce the <html> and <head> it needs, with the Blazor script when it has interactive parts. Rendering inside the host's Routes and MainLayout is what the rendering system of its own will add; a component written to these rules will not change.

One more thing to know: a @page "/" in the host's own Blazor pages hides the CMS home page, since a literal route beats the content routes' catch-all, and so does any @page whose route matches a content address.

12. Reading the content#

The page is found once per request and shared with everything that asks for it:

A shared layout reads the page for its title, whichever view renders the body:

@* Views/Shared/_Layout.cshtml *@
@using Relatude.CMS.Models
@using Relatude.DB.CMS.Web.Rendering
@{
    var page = Context.GetContent<IPage>();
}
<title>@(page?.MetaTitle ?? "My site")</title>
<meta name="description" content="@page?.MetaDescription">

A page bound with [FromContent] is not validated by MVC. Validation would follow every relation of the page and read every related node.

Part V — Site services#

13. CMS settings#

CmsSettings (namespace Relatude.CMS.Settings) is a Relatude.DB custom settings set: one per database, shown as a CMS tab beside the database's settings in the admin UI, and read from code:

var settings = db.Settings.Get<CmsSettings>();
if (settings.Analytics.Enabled) { … }

Values are layered like every custom setting, each layer overriding the one before:

1. the defaults in code;
2. relatude.settings/cms.json, shared and committed with the application;
3. what the admin UI saved on this server;
4. RelatudeDB:CustomSettings:cms in appsettings or environment variables.

{
  "RelatudeDB": {
    "CustomSettings": {
      "cms": { "Analytics": { "Enabled": true, "ExcludedPaths": "/api/, /preview" } }
    }
  }
}

Every CMS setting applies live, without a restart. Further CMS settings go into the same class as new properties and groups in CmsSettingsDefinition, rather than into new settings sets.

14. Page-view analytics#

Analytics records every page view in the database, without cookies and without storing addresses. It is off until CMS › Analytics › Record page views is turned on, and it needs only AddRelatudeCMS() and UseRelatudeCMS().

app.UseForwardedHeaders();        // behind a proxy: first, so the visitor's own address is used
app.UseResponseCompression();     // if at all: before the CMS, which only rewrites uncompressed HTML
app.UseRelatudeDB();
app.UseRelatudeCMS();             // after UseRelatudeDB, before the site's pages and static files

What counts as a page view#

A page view is a GET answered 200 with text/html. These are never page views:

• the admin UI (/relatude.db by default) and the info path the bot check is served from (/-info/);
• paths starting with one of ExcludedPaths;
• pages fetched ahead of a visit that may not happen (Sec-Purpose, Purpose or X-Moz saying prefetch).

Nothing happens while the visitor waits#

The middleware only queues the page view (PageViewQueue, room for 50,000; views beyond that are dropped and counted in Dropped). AnalyticsWorker, a hosted service, waits LookupDelaySeconds so the browser's bot check has time to report, looks up the visitors of a batch of up to 1,000 at once with db.Services.IPLookup, and records the entries. Each address and user agent is looked up once; settled bot or human verdicts are kept for 10 minutes. A failed lookup records the page views without it and warns at most once per 10 minutes.

The bot check#

When InjectBotCheck is on and the database has an IP lookup provider, the bot check script is added to every HTML page just before its last </body>, as HtmlRewriter finds it. Inline (about 500 bytes) by default; turn InlineBotCheck off under a Content-Security-Policy that forbids inline script, and the page loads /-info/bot.js instead. Only an uncompressed UTF-8 HTML 200 of at most 16 MB is held to do it; everything else streams through untouched.

No cookie and no address#

The visitor is a daily visitor hash: SHA-256 of the address, user agent and Accept-Language with a salt of 32 random bytes per UTC day. The salt is held in memory only and never written, so a hash cannot be traced back or linked across days. A restart starts a new salt, so a visitor seen on both sides of it counts twice that day. The referrer is kept as its host only, and the query string is left out unless LogQueryString is on.

The log#

Page views go to the custom log cms-pageviews, Page views under Logs in the admin UI, with daily files kept for 400 days (2,000 MB at most) and statistics for the graphs.

visitorType is human, bot or unknown. Location columns are written only when LogLocation is on and the country is known; browser, operating system and device only for visitors who are not bots.

The log belongs to the database once it is made. It is created when it is missing, and after that changes made in the admin UI (retention, columns taken out, statistics) are kept. The code only adds columns: each column in PageViewLog carries the DefinitionVersion that introduced it as its Since, and the database's storage remembers the version its log has (cms/pageviews-log.json). To add a column, give it the next version and raise PageViewLog.DefinitionVersion.

Testing and replacing the database side#

Everything analytics reads from or writes to the database goes through IAnalyticsHost: the settings, the custom logs, the storage, the IP lookups and the reserved paths. The default is RelatudeAnalyticsHost, on the default database. Register another implementation before AddRelatudeCMS() to replace it; the CMS's own tests use a fake.

15. HTML utilities#

Relatude.CMS.Utils holds a forward-only HTML scanner and a rewriter built on it. Neither builds a DOM or allocates per token, so they are cheap enough to run on every response; analytics uses the rewriter to place the bot check.

Reading#

using Relatude.CMS.Utils;

var images = 0;
var reader = new HtmlReader(html);
while (reader.Read()) {
    if (reader.Kind == HtmlTokenKind.StartTag && reader.Name.Equals("img", StringComparison.OrdinalIgnoreCase)) images++;
}

HtmlReader is a ref struct over a ReadOnlySpan<char>. Each token has a Kind (Text, StartTag, EndTag, Comment, Doctype, CData, ProcessingInstruction), its Name, Raw source text, Start and End offsets, IsSelfClosing, CommentData, and, for start tags, Attributes, which foreach enumerates as HtmlAttributes with Name, Value (still entity-encoded) and Quote. The bodies of script, style, textarea and title are read as text.

Rewriting#

HtmlRewriter.Rewrite copies HTML through and splices in only what a handler changes. The handler can rewrite attribute values, insert markup before a tag, and replace text.

// adds a campaign to every external link in an article body
sealed class CampaignLinks(string campaign) : IHtmlRewriteHandler {
    public string? RewriteAttribute(ReadOnlySpan<char> tag, ReadOnlySpan<char> attribute, ReadOnlySpan<char> value) =>
        tag.Equals("a", StringComparison.OrdinalIgnoreCase)
        && attribute.Equals("href", StringComparison.OrdinalIgnoreCase)
        && value.StartsWith("https://")
            ? string.Concat(value, value.Contains('?') ? "&amp;" : "?", "utm_campaign=", campaign)
            : null;                                    // null leaves the value as it is

    public string? InsertBefore(ReadOnlySpan<char> tag, bool isEndTag) => null;
}

var html = HtmlRewriter.Rewrite(article.Body, new CampaignLinks("autumn"));

HtmlRewriter.ToText suits search snippets and meta descriptions:

var text = HtmlRewriter.ToText(article.Body);
article.MetaDescription = text.Length > 160 ? text[..157] + "…" : text;

16. Donations#

IDonation (namespace Relatude.CMS.Models.Donations) is a generic donation node with the list and detail projection behind the WAF.Client Donations admin module. It does not extend IItem, so a site that only takes donations does not pull in the content model.

The admin module filters the text fields below case-sensitively, so store exactly these values:

A site extends the model with its own interface, and registers both namespaces as datamodel sources (chapter 2). A member may be declared in only one interface of the hierarchy.

namespace MySite.Models;

public interface IMyDonation : Relatude.CMS.Models.Donations.IDonation {
    string Campaign { get; set; }
}

The admin contract#

The admin controller stays in the host, since it derives from the host framework's admin API base (such as WAF's BaseAdminAPIController), which this package does not reference. Routed as wafapi/Donations/{action}, it looks like this:

using Relatude.CMS.Models.Donations.Admin;

[HttpPost]
public DonationListResult List(int pageSize = 25, int pageIndex = 0, string? sortBy = null, bool sortDesc = true,
    string? categories = null, string? statuses = null, string? paymentMethods = null, string? search = null) {
    _ = Context.Session;                               // WAF's admin gate: throws (403) without a session
    var query = _cx.Database.Query<IMyDonation>()      // WhereIn(d => d.Status/…) for non-empty filters
        .OrderBy(DonationAdminProjection.SortExpression<IMyDonation>(sortBy), sortDesc);
    var page = query.Page(pageIndex, pageSize).Execute();
    return new DonationListResult { Rows = page.Values.Select(d => DonationAdminProjection.ToRow(d)).ToList(), TotalCount = page.TotalCount };
}

Get(id) is TryGet<IMyDonation> followed by DonationAdminProjection.ToDetail(d, formGuid: …), where the host resolves the originating form's content guid from FormId. The host also copies the form's name onto FormName when the donation is created, so the list can sort and search by it; a later rename of the form does not change existing donations.

Category and free-text search have no query form. When either is active, the host executes the ordered query, filters with MatchesCategory and MatchesSearch, and then pages.

17. The CMS API#

The CMS API is the NodeStore over HTTP, for a CMS interface running in the browser and for the plugins built into it. It is built the way the Relatude.DB admin UI is: one command endpoint that dispatches on a command's type, and one event stream for everything the server starts. Every request carries a bearer token that names a user node, and the command runs as that user, so queries return only what the user may read.

builder.AddRelatudeCMS()
    .AddApi(o => {
        // the CMS's users have no password of their own: the site says how a sign-in is checked
        o.VerifyLogin = (login, cms) => Task.FromResult(Members.Verify(cms.Admin, login.UserName, login.Password)?.Id);
    });

var app = builder.Build();
app.MapRelatudeCmsApi();   // before MapRelatudeCMS(), whose catch-all route would be tried first
app.MapRelatudeCmsUI();    // the interface itself, at /relatude.cms/ (below)
app.MapRelatudeCMS();

Routes#

Path is {UIPath}/api, so /relatude.cms/api, unless CmsApiOptions.Path says otherwise. A failure answers { error }: 400 for a request the API cannot use (a payload, a value or a query that does not fit), 401 without a valid token, 403 when Authorize says no, 404 for a node that does not exist, 500 for anything else. A command sent with a runId can be stopped with command-cancel and that id; it then answers 499.

Tokens and who a request runs as#

DataProtectionCmsApiTokens, the default ICmsApiTokens, seals a token with ASP.NET Core data protection: it cannot be forged or read, and runs out after TokenLifetime (12 hours). A client renews it with auth/refresh before then. A token of a user deleted since is refused. The tokens outlive a restart only when the data protection key ring does, so a server that keeps no keys signs everyone out when it restarts. Replace the registration of ICmsApiTokens to use tokens of another kind.

The token gives the user, and the payload's context gives the rest of the query context:

Reads are filtered by what the user may read, everywhere: a query applies it, and so do get and exists, which go through a query because a read by id ignores read access. Writes are open to every signed-in user for now. CmsApiOptions.Authorize is called before every command with the caller and the command type, and is the place for access rules until the engine checks writes itself. AllowAnonymous serves requests without a token, as the anonymous visitor, and only commands that read.

Commands#

A write is raw transaction data run by NodeStore.Execute, so the store's transaction plugins run just as they do for a write from C#. transaction runs all its actions in one transaction: all of them happen, or none, and an action may use a node an earlier one inserts. Types, properties and relation ends are named by CodeName or id, and CodeNames match exactly, as in the query language. Locks, revert windows, maintenance and jobs are not commands: they belong to the server's operator.

Nodes and values on the wire#

A node is one object: its properties by CodeName, and the system fields with a $ prefix that no C# name can have.

{
  "$id": "…", "$type": "IArticle", "$displayName": "Five trails worth the climb",
  "$createdUtc": "2026-10-01T08:00:00.0000000Z", "$changedUtc": "…",
  "Title": "Five trails worth the climb", "Price": 149.5, "Tags": ["mtb"],
  "Picture": { "name": "five-trails.svg", "size": 1834, "contentType": "image/svg+xml", "url": "/…" },
  "Parent": { "$id": "…", "$type": "ISectionPage", "Name": "News" }
}

A relation end is there only when the query included it. Dates are ISO 8601 text in UTC, a TimeSpan its invariant c text, a coordinate { latitude, longitude }. HTML comes back with the store's internal links as URLs. Values sent in are parsed strictly by the property's type: a value that does not fit is refused, rather than stored as the type's default. An enum takes its number or its name.

A query result has a kind: nodes (items, totalCount, pageIndex, pageSize, …), values (SelectId), objects (Select), search (hits with node, sample and score), facets (items and facets), pivot (result, for Pivot and GroupBy), path (ShortestPath) or value (Count, Sum). The parameters are typed - string, int, long, double, float, decimal, bool, datetime, datetimeoffset, timespan, guid, geo, or an array such as guid[] - so a decimal property is compared with a decimal and a date with a DateTime, which the literals of the query language cannot all say.

The event stream#

The stream needs the same token. It sends connected with the connection's id first, ping every 10 seconds, which a client also uses to tell a dead connection from a quiet one, and unauthorized when the token runs out. After a command changes nodes it sends nodes-changed, { changes: [{ id, type, kind }] }, to each connection, with only the nodes that connection's user may read; deletions always. Changes made outside the API, by the site or the admin UI, are not sent.

Modules#

A module adds commands of its own the way the built-in ones are registered:

var commands = app.Services.GetRequiredService<CmsApiCommands>();
commands.Register("shop-stock", ctx => {
    var p = ctx.Payload<StockRequest>();
    return ctx.Db.Query<IProduct>().Where(x => x.Sku == p.Sku).Execute().Select(x => x.Stock);
}, readOnly: true);

ctx.Db is the store as the caller, ctx.Root the whole store for checks the server makes on its own behalf, and ctx.Changed(id, typeId, kind) puts a node in the nodes-changed event once the command succeeds. CmsApiEvents.Broadcast(name, payload) sends an event of the module's own.

From TypeScript#

@relatude/sdk (Relatude.UI/packages/sdk) carries the client: a channel to the two routes, a TokenSession, and RelatudeStore, whose methods are the NodeStore's, with a query builder typed by the model's interfaces. The CMS interface in Relatude.UI is built on it, and a plugin gets the same store as cms.store. Chapter 19 covers the SDK, and chapter 20 the plugins.

import { db } from '@relatude/sdk';

const session = new db.TokenSession('/relatude.cms/api');
await session.signIn('ann@velo.example', 'ann');
const store = db.createStore({ baseUrl: '/relatude.cms/api', token: () => session.token() });

const Product = db.nodeType<IProductPage>('IProductPage');
const cheap = await store.query(Product).where(n => n.Price.lte(500)).orderBy(n => n.Name).execute();

The CMS interface#

The interface editors sign in to is not in the package. Its releases are published to services.relatude.com, and MapRelatudeCmsUI() serves the newest one from the site's own address:

Each time the page is asked for, the installation asks services.relatude.com, server to server, which release is the newest: POST {services}/api/cmsui/latest with { apiKey, cmsVersion, installationKey, uiVersion }, uiVersion being the release it holds. Only a release it does not hold is downloaded, from POST {services}/api/cmsui/release, as a zip checked against the SHA-256 the service named. The installation answers its index.html, never cached, with two things put first in its head: <base href="{ui}/r/{version}/">, so every relative URL in the release, its import map's included, points at that release's files, and window.__RELATUDE_CMS__ = { api, uiPath, version, cmsVersion }, which tells the interface where its API is. The files are served from memory and cached by the browser as immutable, since the version is in their path. CmsUiServer keeps the last three releases, so a page loaded before a new release keeps working, and the zip of the one it serves in the database's storage (cms/ui/), so a restart does not download it again. That copy is what is served while the service cannot be reached. A refusal, or no release published, is never answered with it.

The CMS takes a license with the feature cms. The server's ApiKey setting (the admin UI's Settings, or RelatudeDB:ApiKey in appsettings) goes with every request, to the ServicesServerUrl setting (https://services.relatude.com) unless CmsApiOptions.ServicesUrl is set. When there is nothing to serve, a short HTML page says why: 503 with no API key, 403 and the service's reason when it refuses the key, 404 when no release is published, 502 when the service cannot be reached and no copy is kept. The service counts each opening and download, per release and per installation.

The path is set as /relatude.db's is. The server setting CMS > Hosting > CMS path (CmsServerSettings.UIUrlPath, file key cms-server), read when the application starts, wins over CmsApiOptions.UIPath. The API moves with it, to {ui}/api, unless CmsApiOptions.Path is set.

A release has a version of its own, apart from the package's, and every installation serves the newest release whatever CMS version it runs. Relatude.UI/publish.bat builds the interface, asks the service for its latest release, suggests the next version and publishes the build to services.relatude.com/publishcmsui with the publish key from Relatude.DB.Secrets. Releases come from ICmsUiSource, ServicesCmsUiSource by default; register another to serve them from elsewhere.

18. Modules#

A module is everything one feature adds to a site, described in one class and shipped in one assembly, usually a NuGet package. The site adds it with one line, and the module brings the rest: its model types, transaction plugins, jobs, settings for each database and for the server, seed data, commands of the CMS API, routes, rendering, views, an interface plugin, custom logs and user groups, and what it needs of other modules and of the license.

The module is the package. The plugins it brings are smaller parts that each hook into one thing: a transaction plugin into the store's writes, an interface plugin into the CMS interface (chapter 20). An interface plugin can also come without a module, listed in the CMS settings.

EventsModule/, beside Website2, is a worked example of every part: three modules in one assembly (venues, events at them, and SMS reminders, which need the license). Its README says how to see each part working on Website2.

A module#

A module is a class deriving from CmsModule (namespace Relatude.DB.CMS.Modules). It has a name, and Configure says what it is made of:

public sealed class EventsModule : CmsModule {
    public override string Name => "events";
    public override string Title => "Events";
    public override string Description => "Events at venues, with registration and a calendar feed.";

    public static readonly Guid Managers = new("6549f757-c808-4c73-bac2-ea96b826ef49");

    // an option of the module's, which the host sets when it adds it
    public Guid? ParentPageId { get; init; }

    public override void Configure(CmsModuleBuilder module) {
        module.Services.AddSingleton<EventCalendar>();
        module
            .DependsOn<VenuesModule>()
            .Datamodel(dm => dm.AddNamespace<IEventPage>())
            .TransactionPlugin<EventPagePlugin>()
            .Job("events.close-past", "Marks the events that have ended as ended.", closePast)
            .Settings<EventSettingsDefinition>()
            .Settings<EventServerSettingsDefinition>()
            .Seed(1, "Three events at the venues", EventSeed.Events)
            .Seed(2, "A first registration", EventSeed.Registration)
            .Seed(3, "Events listed under the site's page", c => EventSeed.ListUnder(c, ParentPageId))
            .UserGroup(Managers, "Event managers")
            .Log(EventActivity.Definition())
            .OnStoreOpened(c => …)
            .Command("events.upcoming", EventCommands.Upcoming, readOnly: true)
            .Command("events.cancel", EventCommands.Cancel)
            .Endpoints(EventEndpoints.Map)
            .Rendering(o => o.RenderRazorView<IEventPage>("EventPage"))
            .Views()
            .InterfacePlugin();
    }
}

The work done on a store gets a CmsModuleContext: the store as the master admin (Store), the application's services (Services) and the module itself (Module).

Adding modules#

builder.AddRelatudeCMS()
    .AddApi()
    .AddModule<VenuesModule>()
    .AddModule(new EventsModule { ParentPageId = SiteSeeder.HomeId })
    .AddModule<EventRemindersModule>();

AddModule runs Configure at once: the module's services, settings and rendering are added then, and the rest waits for the start of each database. A module added twice is added once, so a module can be added by a package and by the host without harm. The name is letters, digits and -, starting with a letter, and must be the module's own.

A module builds on another with DependsOn<T>(), and the other must be added too, before or after. The modules are ordered with their dependencies first, otherwise in the order added. A missing dependency, or modules that build on each other in a circle, stop the site at UseRelatudeCMS() with a message naming them, before any database opens.

Modules are added in code, never discovered by scanning assemblies: installing a .NET module takes a build and a restart anyway, and Program.cs then says what runs, and in which order.

The database's start#

The modules take part in every database's start through three services Relatude.DB calls (chapter 2), which AddRelatudeCMS() registers. No setup call of the host's can lose them.

1. The datamodel (IDatamodelInitializer). After the host's OnDatamodelInit, every module that applies adds its model types, dependencies first. A module applies to a database whose datamodel has the CMS content model (IItem), unless AppliesTo says otherwise, and never to one without a module it builds on.
2. The store, before it opens (IStoreInitializer). Every module that is part of the database registers its transaction plugins, task runners and jobs. This is done whether or not the module is active, so its data stays guarded while it is turned off.
3. Once the store is open (IStoreOpenHandler), on a background thread, so the opening does not wait. For every module that is part of the database and active, dependencies first: its user groups and custom logs are made where missing, its seed steps not run yet are run, and its start-up work is done.

A module is part of a database only when its model types went into that database's datamodel, which is also what CmsModules.IsPartOf(name, store) answers.

Seed data#

Seed data is numbered steps, each run once per database, in order:

.Seed(1, "Two venues", c => {
    if (c.Store.TryGet<IVenue>(Workshop, out _)) return;            // a step finds what an earlier run made
    c.Store.CreateAndInsert<IVenue>(v => { v.Name = "The workshop"; v.Seats = 24; }, Workshop);
})

• The database remembers the last step it ran, in its storage: cms/modules/{name}.json. A module new to a database runs every step; a module that gets a new step in an update runs that one step at the next start. That makes a step the place for a change to data as well as for the first data.
• A step that throws stops the steps after it, and the error is logged. They are tried again, with it, at the next start.
• Never renumber a released step. A database that ran step 2 never runs a step 2 again.
• Give seeded nodes fixed ids, so a step finds what it made, and later steps and other modules can find it too.
• Steps run as the master admin, through the store's synchronous writes, so the transaction plugins see what they write.

CmsModules.SeedVersionOf(name, store) answers the last step a database ran.

Transaction plugins and jobs#

TransactionPlugin<T>() registers a NodeTransactionPlugin made with the application's services. A write reaches it in one of two forms, and a rule about values has to check both:

• the whole node (OnBeforeNodeAction): an insert, an update of a loaded node, an upsert;
• some of its properties (OnBeforePropertyAction): how the CMS API's update command, and so the CMS interface, saves, sending only what changed.

public override void OnBeforePropertyAction(NodeKey key, Guid[] propertyIds, NodePropertyOperation operation,
        object[]? values, Transaction transaction, PropertyHelper<IEventPage> helper) {
    // the values written, by property id; the rest as stored
    var stored = helper.GetNodes([key.Guid]).FirstOrDefault();
    …
}

Job(name, description, run) registers a job on each store, which the admin UI's scheduler can run at set times or by hand (Tasks › Scheduler). The schedule is the administrator's: the module only says what the job does. While the module is not active, a run does nothing and reports why.

Settings#

Settings<TDefinition>() registers a custom settings set: a tab of its own in the admin UI, beside each database's settings or the server's, as the definition's Scope says. It is read like any other:

var settings = db.Settings.TryGet<EventSettings>(out var s) ? s : new();          // per database
var server = RelatudeDBRuntime.Server.CustomSettings.Get<EventServerSettings>();  // per server

TryGet keeps code working where the set is not registered, in a test, say.

Commands#

Command(type, handler, readOnly) adds a command to the CMS API (chapter 17). It runs as the signed-in user like the API's own: ctx.Db reads with the user's access, ctx.Root is the whole store, ctx.Payload<T>() reads the payload, and ctx.IsInGroup(groupId) says whether the user is a member of a group, directly.

public static object? Cancel(CmsApiContext ctx) {
    if (!ctx.IsInGroup(EventsModule.Managers)) throw new CmsApiException(403, "Only event managers may cancel an event.");
    var id = ctx.Payload<CancelPayload>().Id;
    var e = ctx.Db.Query<IEventPage>().Where(id).Execute().FirstOrDefault() ?? throw new CmsApiException(404, "There is no such event.");
    e.Status = EventStatus.Cancelled;
    ctx.Db.Update(e);
    ctx.Changed(e.Id, e.Meta.NodeTypeId, CmsApiChangeKind.Updated);   // tells the open CMS interfaces
    return new { cancelled = true };
}

Commands are named after their module, events.cancel, and adding one named otherwise throws, so a module can never replace another module's command or one of the API's own. While the module is not active its commands answer 403 with the reason. The CMS interface sends one with cms.store.send("events.cancel", { id }).

Routes#

Endpoints(e => …) maps routes of the module's own, for visitors rather than editors: a feed, a form post, a webhook. MapRelatudeCMS() maps them, in a group of the module's. While the module is not active they are left out of routing, so a request falls through to whatever else answers it, or a 404.

endpoints.MapGet("/events.ics", (HttpContext http, RelatudeCmsContext cms, EventCalendar calendar) => …);
endpoints.MapPost("/events/{id:guid}/register", register).DisableAntiforgery();

A route reads as the visitor through RelatudeCmsContext.Db, and writes as the master admin through .Admin, after checking what the visitor may do.

Rendering and views#

Rendering(o => …) adds to the site's one set of rendering options (chapter 8): code defaults for the module's types, selectors, template kinds. Views() makes the views, controllers and Razor Pages compiled into the module's assembly part of the application, so a module built as a Razor class library (Microsoft.NET.Sdk.Razor, AddRazorSupportForMvc) brings the views its code defaults name. The site's own _ViewStart gives them the site's layout.

A module's pages get their URLs from the site's URL manager (chapter 6). On a site whose URLs follow a tree, the module's types need a parent there: the events module has a relation for it, EventParent, and Website2 names it among its URL parents, so an event under the home page is at /autumn-trail-day.

The interface plugin#

InterfacePlugin() gives the module a plugin for the CMS interface (chapter 20): an ES module whose default export is definePlugin(…), embedded in the module's assembly with the files it imports:

<EmbeddedResource Include="ui\**" LogicalName="cms-ui/%(RecursiveDir)%(Filename)%(Extension)" />

• The CMS API serves the files at {api}/modules/{name}/{version}/…, cached by browsers as immutable, since the version is in the path. The version is the assembly's informational version unless the module overrides Version.
• As it starts, the CMS interface sends cms-modules and imports the interface plugin of every active module. Its bare imports resolve through the interface's import map, so it shares the interface's React, SDK and components.
• The plugin can be plain JavaScript, with createElement in place of JSX and no build step, as the example's is, or built with @relatude/plugin-kit into the folder that is embedded.
• A module added without its embedded entry stops the start, saying how to embed it.

Interface plugins without a module#

An interface plugin needs no module when it has no server code: the CMS settings list it (the admin UI's CMS tab, Interface plugins: a name, an address, and whether it loads). The address is a path on the site (/cms-plugins/site-tools.js, from its wwwroot) or an address on another site that allows it (CORS). A plugin runs with the signed-in editor's access, so add only one you trust.

Turning a module off#

CMS › Modules › Modules turned off lists the modules to turn off, by name, separated by commas. It applies at once.

Nothing stored is lost or left unguarded, so turning a module on again is only that. A module that builds on one turned off is off too.

The license#

RequiresLicense("sms") keeps a module inactive while the installation's license is known not to carry the feature: no API key, an invalid one, a license disabled or run out, or one without the feature. The license is asked through ICmsLicense, by default RelatudeCmsLicense, which asks Relatude Services with the server's API key, at most every ten minutes. While the license server cannot be reached, the module is given the benefit of the doubt: what was known stays known, and nothing known stays unknown.

Where a module stands#

CmsModules.StatusOf(name, store) answers where a module stands on a database, with the reason when it is not active:

The CMS interface lists the modules under Settings → Modules, each with its state, what it brings and how far its seed data has come, and every interface plugin under Settings → Plugins: the built-in ones, the modules', those of the CMS settings, and those added in the browser. The cms-modules command answers both:

{ "modules": [
    { "name": "events", "state": "active", "version": "1.0.0",
      "interfacePlugin": "/relatude.cms/api/modules/events/1.0.0/index.js", "dependsOn": ["venues"],
      "commands": ["events.upcoming", "events.cancel"], "jobs": ["events.close-past"],
      "settings": [{ "fileKey": "events", "title": "Events", "scope": "database" }], "seedSteps": 3, "seedVersion": 3 }
  ],
  "interfacePlugins": [
    { "name": "site-tools", "url": "/cms-plugins/site-tools.js", "enabled": true }
  ] }