Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

Declare sections and slots

Your shop says which sections editors build pages from and where they go. Editors build templates and pages from them in the admin.

OrbPage holds what editors write about your products: a category's story, the home page, an imprint, the footer's menu. It never decides how that looks. Your shop declares the building blocks in code, and editors arrange them in the admin's Content area:

WordWhat it isWho makes it
SectionA building block with typed settings, such as a hero with a title, a picture and a button.The shop
SlotA place on a kind of page that takes a list of sections, such as a category page's top.The shop
PaletteThe shop's own colours, by name. Editors see swatches; the shop gets the name.The shop
MenuA place the shop shows links an editor arranges, such as the footer.The shop
TemplateWhat every category that follows it shows in each slot, built from the shop's sections.An editor
PageA category's page, the home page or a page of the shop's own, built from the same sections.An editor

Declare them

declare from @orbpage/client takes the whole declaration and gives back OrbPage's contract together with the types your renderers read. Nordgrat's, shortened:

import { declare, setting } from "@orbpage/client";
import type { BodyOf, HomeSlotsOf, SectionOf, SlotItem, SlotsOf } from "@orbpage/client";

export const sections = declare({
  palette: {
    snow: { label: "Snow", value: "#f6f4ef" },
    moss: { label: "Moss", value: "#3e5a48" },
  },
  sections: {
    hero: {
      name: "Hero",
      settings: {
        title: setting.line("Title").describe("A few words that name the page."),
        text: setting.text("Text").optional(),
        picture: setting.picture("Picture").optional(),
        link: setting.link("Button link").optional(),
        label: setting.line("Button text").optional(),
        tone: setting.colour("Background"),
      },
    },
    text: {
      name: "Text",
      settings: {
        body: setting.text("Text"),
        width: setting.choice("Width", { narrow: "Narrow", wide: "Wide" }),
      },
    },
    productRow: {
      name: "Product row",
      settings: {
        title: setting.line("Title").optional(),
        products: setting.products("Products", { max: 12 }),
        columns: setting.number("Columns", { min: 2, max: 4 }).default(4),
      },
    },
  },
  slots: {
    category: {
      top: { name: "Top", sections: ["hero"] },
      main: { name: "Main", sections: ["text", "productRow"] },
    },
    page: {
      body: { name: "Body", sections: ["text"] },
    },
    home: {
      body: { name: "Body", sections: ["hero", "text", "productRow"] },
    },
  },
  menus: { footer: { name: "Footer" } },
});

/** A section as the shop renders it, by its type. */
export type Section = SectionOf<typeof sections>;
/** A category page's slots, each a list of sections. */
export type CategorySlots = SlotsOf<typeof sections>;
/** A page's body. */
export type PageSlots = BodyOf<typeof sections>;
/** The home page's slots. */
export type HomeSlots = HomeSlotsOf<typeof sections>;

A slot names only sections you declared, so a typo fails as you type. OrbPage's contract checks the rest as the shop starts, never at a shopper's request. The home page uses slots.home, independently of slots.page for other pages. Both default to no slots when omitted. The editor, draft validation, publishing and delivery use the same declaration; home.get() is typed from home slots and pages.get() from page slots.

The settings a section can have

Each setting is delivered as the shop reads it, not as the editor stored it: a product is a card with its title, address and picture, a link is an address, running text is safe HTML. A script that writes content sends the stored form.

SettingStored asDelivered asEmpty?
setting.line(label)a string of at most 300 charactersa stringwith .optional()
setting.text(label)a document{ html }, an HTML fragment safe to insertwith .optional()
setting.picture(label){ media, decorative? }, a library file's id{ url, width, height, alt, srcset?, focalPoint? }with .optional()
setting.link(label)a link, such as { kind: "page", id }{ href }, to a product, a category, a page or a URLwith .optional()
setting.products(label, { max })picked refs, or a category's ref and limitproduct cards, picked or a category's first onesan empty list
setting.categories(label, { max })the catalog's category refscategory cardsan empty list
setting.pages(label, { max })pag_ ids, never the home page'spage cards, in the order pickedan empty list
setting.form(label)a frm_ idone of the site's forms, with its fieldswith .optional()
setting.choice(label, options)an option keyone of the option keys; the first is the defaultnever
setting.toggle(label)a booleana boolean, off unless .default(true)never
setting.number(label, { min, max })a whole numbera whole number, min unless .default(n)never
setting.colour(label)a palette namea palette name; its first colour unless .default(name)never

A link stores its target by identity: { kind: "page", id }, { kind: "category", ref }, { kind: "product", ref }, { kind: "path", path } or { kind: "url", href }. A category or a product is always named by the catalog's ref, never its slug, so a renamed address still resolves. Products store { kind: "references", refs } or { kind: "category", ref, limit }.

A page card holds id, title, href and publishedAt, when the page was first published in that locale. It carries no picture and no description.

.describe(help) puts a line of help beside the setting in the editor. A line, a text or a picture may also come from the catalog: on a category's page an empty title is the category's name, an empty picture its picture. Such a setting stores { "follow": "name" }, { "follow": "description" } or { "follow": "picture" }; only a category's page may follow.

Write long texts

An editable writing area grows with short text, up to 60% of the dynamic viewport height. Longer text scrolls inside it while its formatting toolbar stays above the text, without covering the selection or the admin header. Formatting, links and block insertion keep the current selection. Native scrolling continues through the page at the writing area's edge; the toolbar leaves with its editor. Read-only text remains fully expanded.

Render a slot

Section is a discriminated union, so a switch over its type is exhaustive and each case reads its own settings, typed:

import { PageLayout } from "@orbpage/react";

function Slot({ sections }: { sections: readonly SlotItem<Section>[] }) {
  return (
    <PageLayout items={sections}>{(section) => <ContentSection section={section} />}</PageLayout>
  );
}

function ContentSection({ section }: { section: Section }) {
  switch (section.type) {
    case "hero":
      return <h1 className={`tone-${section.settings.tone}`}>{section.settings.title}</h1>;
    case "text":
      return <div dangerouslySetInnerHTML={{ __html: section.settings.body?.html ?? "" }} />;
    case "productRow":
      return (
        <ul>
          {section.settings.products.map((product) => (
            <li key={product.ref}>
              <a href={product.url}>{product.title}</a>
            </li>
          ))}
        </ul>
      );
  }
}

A section of a type your code does not know yet is left out of the answer, and a slot it does not know of is empty. A deploy that adds a section never breaks a page the older code renders.

Arrange rows

Editors may leave sections directly in a slot or add explicit rows. Existing pages keep their flat shape. A row carries kind: "row", a stable row_… id, a named layout and columns: each column is an ordered list of the slot's existing section types, never another row.

The presets are full, halves, thirds, quarters, oneTwo (1:2) and twoOne (2:1). Four equal columns are exact quarters. PageLayout renders these proportions and stacks all columns in content order when its container becomes too narrow, independently of window size. The default column gap is 1.5rem, customizable with --orbpage-row-gap.

Preview and published delivery carry the same layout. Keep each section's preview mark inside PageLayout so clicking it still opens its editor. A text setting's HTML fragment remains just that text; layout lives in the surrounding row, not in its HTML. Markdown reads columns in content order without visual layout markup.

Add row chooses a preset. Move to sends an existing section to a row's column or outside rows; ordinary move controls reorder sections and rows. Reducing the column count appends the removed columns' contents to the last remaining column, without changing section ids. Structural edits can be undone. The 100-section slot limit includes all columns. Category templates have the same rows and the same follow/reset behavior as flat content, not a separate page-template system.

Push them to OrbPage

Your deploy pushes the declaration, as Nordgrat's pnpm content does. With check, OrbPage only reports what would change and which drafts and live versions would no longer fit:

import { declareSections } from "@orbpage/client";

const options = { baseUrl: process.env.ORBPAGE_URL, token: process.env.ORBPAGE_STAFF_TOKEN };

const checked = await declareSections(sections, { ...options, check: true });
if (!checked.ok) throw new Error(`OrbPage refused the check: ${checked.problem.code}`);
for (const { change, what, name } of checked.content.changes) console.log(change, what, name);
for (const { kind, key, state } of checked.content.misfits) {
  console.log(`No longer fits: the ${state} ${kind} ${key}`);
}

const declared = await declareSections(sections, options);
if (!declared.ok) throw new Error(`OrbPage refused the sections: ${declared.problem.code}`);

The token is a staff token with Content edit, as the admin's /api/auth/token answers once you are signed in; Write content from code shows how a script gets one. declareSections and manageContent(options).declare(declarations, key) are the same operation. declareSections takes what declare returned; manageContent sends sections.declarations with an idempotency key, checks with checkDeclarations, and also takes an operator key. Content that no longer fits stays stored; delivery shows only what still fits, and a setting with a default holds it until an editor picks another.

Templates

Editors build templates in the admin from the sections a category's slots take. Every category follows the default template until an editor picks another. A slot shows the template's sections until the editor changes that slot for one category; from then on the slot is the category's own, and a reset gives it back to the template. The shop never sees the difference: it reads the category's page, slot by slot, and the answer names the template it follows.

How the shop reads pages, menus and previews: Read the content.

Size an image in running text

Each image block has its own Display width: full width, 50%, one third, 25%, or a custom positive whole pixel width. Original appearance removes the choice and leaves the image as it appeared before. The same library image can therefore be a small logo on one page and full width on another.

The chosen width survives saving, preview and publishing. The delivered HTML fragment sizes the complete figure, keeps its caption and link, preserves image proportions and never makes it wider than its container. Custom pixel widths must be positive safe integers; unfinished or invalid input remains in the draft so the editor can correct it before publishing.

On this page