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:
| Word | What it is | Who makes it |
|---|---|---|
| Section | A building block with typed settings, such as a hero with a title, a picture and a button. | The shop |
| Slot | A place on a kind of page that takes a list of sections, such as a category page's top. | The shop |
| Palette | The shop's own colours, by name. Editors see swatches; the shop gets the name. | The shop |
| Menu | A place the shop shows links an editor arranges, such as the footer. | The shop |
| Template | What every category that follows it shows in each slot, built from the shop's sections. | An editor |
| Page | A 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.
| Setting | Stored as | Delivered as | Empty? |
|---|---|---|---|
setting.line(label) | a string of at most 300 characters | a string | with .optional() |
setting.text(label) | a document | { html }, an HTML fragment safe to insert | with .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 URL | with .optional() |
setting.products(label, { max }) | picked refs, or a category's ref and limit | product cards, picked or a category's first ones | an empty list |
setting.categories(label, { max }) | the catalog's category refs | category cards | an empty list |
setting.pages(label, { max }) | pag_ ids, never the home page's | page cards, in the order picked | an empty list |
setting.form(label) | a frm_ id | one of the site's forms, with its fields | with .optional() |
setting.choice(label, options) | an option key | one of the option keys; the first is the default | never |
setting.toggle(label) | a boolean | a boolean, off unless .default(true) | never |
setting.number(label, { min, max }) | a whole number | a whole number, min unless .default(n) | never |
setting.colour(label) | a palette name | a 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.