Relatude Help

Relatude.CMS

A practical manual

Relatude.CMS is the content layer on top of Relatude.DB, the open-source object 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 and groups;
  • page rendering with MVC views, controllers, Razor Pages or any IResult;
  • CMS settings, cookie-free page-view analytics, fast HTML utilities and a donations model;
  • an HTTP API and a TypeScript SDK for the CMS interface that editors work in, and for the plugins that extend it.

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

  • 1 What Relatude.CMS is — Relatude.CMS is a class library with no entry point. Your ASP.NET Core application hosts it: the application starts Relatude.DB, adds the CMS and decides how pages look. The CMS supplies the parts every content site…
  • 2 Setting up the host
  • 3 Content types — Content types build on IItem. Routable content is an IPage.
  • 4 The other base types — A site is both a collection and a page. Let your home page type extend ISite, as in Everything together, and each home page is a site at the top of its own tree. The CMS interface shows one site's tree at a time (chapter…
  • 5 Templates — A template is a layout an editor can choose for a page. If every page of a type looks the same, you need no template: code says what renders the type (chapter 8). If editors choose, say between a standard and a wide…
  • 6 Addresses and URLs — A URL is never stored. A page has an address, one path 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…
  • 7 Answering a request
  • 8 What renders a page — Two things can say what renders a page: code, once per page type, or a template that an editor chooses for the page. A site can use either or both. Code is the simplest: one line per type, and nothing in the database…
  • 9 MVC views and controllers
  • 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.
  • 11 Any IResult: Blazor, JSON and the rest — A ResultTarget returns any IResult, so it needs neither MVC nor Razor Pages. Use it for JSON to a headless client, a file, a template engine of your own, or a Blazor component rendered on the server.
  • 12 Reading the content — The page is found once per request and shared with everything that asks for it:
  • 13 CMS settings — CmsSettings (namespace Relatude.CMS.Settings) holds the CMS's settings for one database. The admin UI shows them on a CMS tab beside the database's own settings. Code reads them like this:
  • 14 Page-view analytics — Analytics records every page view in the database, with no cookie and no stored IP address. Turn it on in the admin UI under CMS › Analytics › Record page views. It needs nothing beyond AddRelatudeCMS() and…
  • 15 HTML utilities — Relatude.CMS.Utils has a forward-only HTML scanner and a rewriter built on it. Neither builds a DOM or allocates per token, so both are cheap enough to run on every response.
  • 16 Donations — IDonation (namespace Relatude.CMS.Models.Donations) is a generic donation node, with the list and detail projections behind the WAF.Client Donations admin module. It does not extend IItem, so a site that only takes…
  • 17 The CMS API — The CMS API is the NodeStore over HTTP. The CMS interface runs on it, and so do its plugins. It has one command endpoint, which dispatches on the command's type, and one event stream. Every request carries a bearer token…
  • 18 Modules — A module is the package one feature comes in: a class that describes everything the feature adds, shipped in one assembly, usually a NuGet package. The site adds it with one line. A plugin is a smaller part that hooks…
  • 19 The TypeScript SDK — @relatude/sdk is the client for the CMS API (chapter 17): Relatude.DB's NodeStore and query builder in TypeScript, typed by your model's interfaces. Queries run on the server as the signed-in user, so they return only…
  • 20 Plugins for the CMS interface — The CMS interface is the editors' application, served at /relatude.cms/ (chapter 17). A plugin adds a menu item, a screen, a dashboard card, search results or a property editor to it. The interface's own Dashboard…
  • 21 API reference — The public types a site, a module or a plugin uses, by area. The setup methods are extension methods in the global namespace, so Program.cs needs no using for them.
  • 22 Pitfalls
  • 23 Every feature in one Program.cs — Every option this manual describes, in one host, set the way a real site would set it. Each group of lines names the chapter that explains it. No site needs all of it: start from the smallest setup in chapter 2.
  • Where to look when this manual runs out — The Relatude.DB manual: modelling, queries, transactions, files, the URL manager, custom logs and settings. The doc comments of the Relatude.DB.CMS package, which your editor shows for its public types and members. The…