Pages and slots

Pages

A page is a Razor page built in code, or a page an editor added from a template built in code (see Let editors add pages). SunBird identifies it by a page key. A code page sets its key with the [SunBirdPage] attribute on its PageModel; a created page gets a generated one:

[SunBirdPage("about")]
public class AboutModel : PageModel
{
}

The key is an opaque identifier. It is not the URL, so a page's URL can change without losing its content. Keys are 1 to 100 characters of ASCII letters, digits, -, _ and ..

SunBird stores nothing for a page until an editor first saves it.

Slots

A slot is one editable piece of a page. There are six kinds:

Tag helper Kind Holds
<sb-text> Text Plain text, HTML-encoded when rendered.
<sb-html> Rich text HTML, written by SunBird when saved from the editor's structured document, using only p, h2 to h4, ul, ol, li, blockquote, hr, strong, em, s, sup, sub, a href (with target="_blank" rel="noopener" for a new-tab link) and br.
<sb-image> Image A reference to an image in the media library, plus its alt text.
<sb-link> Link A link's text, and where it goes: a page of the site, or an address.
<sb-file> File A download link's text, and a reference to a PDF in the media library.
<sb-table> Table A table's column headings, and its sections of rows, all plain text.
<sb-icon> Icon The name of a Material Symbols icon, such as home.

Each slot has a key that is unique on its page, with the same character rules as page keys.

A slot belongs to the page being served, not to the file it is written in. Slots can be in a page's partials, and a partial used on several pages gives each page its own slots. To use a partial more than once on the same page, wrap each use in <sb-scope key="…">, which prefixes the keys inside it (top.hero-title). See Make a page editable.

For a list of the same thing, such as gallery pictures or testimonials, <sb-repeater key="gallery"> repeats its content once per entry, and editors add, remove and reorder the entries. Each entry's slots are stored under the repeater key and the entry number (gallery.2.caption). See Repeat parts of a page.

Content shown on many pages, such as testimonials or a footer, can be a fragment: a partial view with [SunBirdFragment("testimonials")], shown with <sb-fragment name="_Testimonials" />. Its slots belong to the fragment, not the page, so editors change them once for every page, and it has its own history. See Share content between pages.

Default content lives in the markup

The content inside a slot tag is its default:

<h1><sb-text key="hero-title">Build calm, fast websites</sb-text></h1>

The page shows the default until an editor publishes a value. The developer or agent who builds the page decides the placeholder.

Rules

  • Public page views never write to the database. A page shows the published value of each slot, or else its markup default.
  • Slots belong in pages and the partials they render. A slot in a layout, or in a section a layout renders, is always logged. In Development, and on staging with ShowSlotErrors on, the page shows a clear error in place of the slot. On the live site the slot shows its markup default. See Settings.
  • Headers, footers and other layout content are managed in code, except for fragments (<sb-fragment>), which may be in layouts.
  • Removing a slot from a page's markup is safe. Its saved values stay in the page's history and are simply not rendered.
Edit this page