Template Designers: Template Sections
Agree on each section's content, behavior, and states. The CMS stores sections as Page.pageItems entries; which type values and config keys exist is decided by the selected template repository, not by the schema.
Shared section requirements
Every section in your design becomes a pageItems entry with these stored fields (see the PageItem fields):
type: a string naming the section component the template renders.order: the section's position on the page.config: a free-form JSON object holding the section's options and editable values.content: a text payload, where the section uses one.objectType/objectId: optional pointers linking the section to another record (for example a specific post or category). Their meaning is template-defined.
For each section, document its purpose, editable fields, required and optional content, image treatment, destinations, and responsive behavior. Use the exact type value and config keys from the selected template when handing off implementation details. Show long text, missing optional fields, and relevant loading, empty, error, and success states. Keep type strings and config keys stable during a presentation-only change.
Promotional and editorial sections
These are common patterns, not a list of components guaranteed to exist in every template:
- Hero: headline, supporting text, background or featured image, primary action, and optional secondary action. Show image crop and text behavior on mobile.
- Banner: a focused message with an optional image and action. Define how it works without a background image.
- Image with text / About: heading, body copy, image, and optional link. Specify reading order on narrow screens.
- Text: heading, body content, and optional action. Show headings, lists, links, and long text if supported.
- Gallery: title, description, and images. Define captions, alternative text, cropping, empty state, and any supported viewer interaction.
- Video: heading, introduction, supported video URL, and a poster or fallback. A
Postcan also carryvideoUrl,video, andaudioattachments. Show loading or unavailable-media behavior. - Carousel: slide content, actions, and controls. If automatic movement is supported, define pause and manual navigation behavior.
Forms and contact sections
Forms need field labels, instructions, required indicators, validation messages, submission progress, success confirmation, and a recoverable failure state. Include the intended destination of the submission so the developer can check the full flow.
A contact section may combine an inquiry form, address, phone, email, social links, and a map. Show the layout without optional fields and provide a useful alternative when the map cannot load. Site-level social links belong in Web.externalLinks; page-specific contact details belong in the section's config.
A booking or reservation section depends on an implemented integration in the template. Agree on dates, guest counts, availability, pricing, validation, and confirmation behavior with the owning team; these are not generic CMS page fields.
Lists and personalized content
Post, category, product, and other collection lists need card content, image treatment, ordering, destination links, pagination or expansion behavior, and empty results. Build cards from real fields:
Post:title,slug,excerpt,thumbnail,publishedDate,categories,tags,viewCount, andauthorId/authorKind.PostCategory:name,slug,description,parentId.PostTag:name,slug,colorCode.
Publication time and record-creation time are different fields: publishedDate vs. createdAt. Choose the intended one for the card. A Post.author union to the core User type exists, but what a template displays as a byline depends on its own implementation; agree on it with the developer.
For recently viewed or personalized sections, define the first-visit state and the no-history state. Whether personalization exists is determined by the template and its integrations, not the CMS.
Handoff checklist
| Per section | Stored in | Specify |
|---|---|---|
| Section identity | pageItems[].type | Exact type string the template expects |
| Position | pageItems[].order | Where it sits on the page |
| Editable options | pageItems[].config | Each key, its type, default, and constraints |
| Text payload | pageItems[].content | Format: plain text, HTML, or markdown |
| Linked record | objectType/objectId | What the section may point at |
| Dynamic states | Template component | Loading, empty, error, long-content variants |
Section handoff
For each section, include a populated example and its alternate states, the editable field mapping, shared tokens, media assets, and responsive variants. Flag new fields or interactions that require development. A new config key is cheap to store but still needs a component that reads it.
