Layouts
A layout is a React component that defines a page’s shell: where the header, footer and placeholders go. For how people use layouts in Visor, see the User Guide.
How a layout is chosen
The template looks in this order and uses the first match:
- Path mapping:
xtr_cms_slug_layout_configuration, for published pages only and not in preview. - The item’s own layout: the page or item’s Layout field.
- The content type’s layout:
xtr_cms_content_type_layout. - The local fallback.
components/Layout.tsx then finds the component by name. If it can’t find one, it uses VdsLandingLayout.
Platform layouts
| Layout | Name in Visor | Placeholders |
|---|---|---|
VdsLandingLayout | Landing page | Header, Main, Footer |
VdsContentLayout | Content page with sidebar | Header, Main, Left, Right, Footer |
VdsArticleLayout | Article page | Header, Main, Left, Right, Footer |
Older layout names still work and resolve to these. BaseLayout, HomepageLayout and EmptyBlockLayout become Landing. InnerpageLayout, GroupPageLayout, PageNavigationLayout and ServerPageNavigationLayout become Content. ArticleLayout becomes Article.
Placeholders
The placeholder names are Header, Main, Left, Right and Footer. In the page editor, people can drop widgets into Main, Left and Right. In the layout builder, every placeholder accepts them.
Create a site layout
The create-layout skill does all of this for you. Here’s what it creates:
- SiteLanding.tsx
- ClientSiteLanding.tsx
- site-landing.scss
Write the server layout
Create components/layouts/<Name>.tsx. It default-exports the component and exports layoutJsonConfiguration. Delegate to the client variant in draft mode, and pass content to placeholders untouched, because multilanguage depends on it.
export const layoutJsonConfiguration = {
name: "Site landing",
layout: "SiteLanding", // Must equal the file name
widgets: [
// One entry per seeded widget, and a full "empty" entry
// for each placeholder that has no seeded widget.
{
id: "empty",
collection: "empty",
sort: 1,
item: {
id: "empty",
name: "empty",
placeholder_definition: { name: "Main" },
widget_definition: { name: "empty" },
parameters: {},
},
},
],
};A placeholder without a seeded widget needs that full empty entry, or it won’t appear in Visor’s editor.
Write the client variant
Create components/layouts/client/Client<Name>.tsx, using WidgetProvider, ClientPlaceholder and useParentDragBridge. It’s required for the layout builder to open it.
Add its styles
Put them in styles/site/layouts/<name>.scss, and add a @use line for it in styles/site/index.scss.
Check it
Your layout should appear in http://localhost:3000/api/layouts, and in Visor in Developer mode.
Merge and set it up
There’s no code registry. After you merge it, it appears in Visor. A page can use it only once it’s set up: open and save it in Visor’s Layouts, or use visor_layout_configure. visor_preview_wait also sets up new layouts after a merge.
Naming
A site layout’s name must not match a file in platform-layouts/, because the platform’s wins and a warning is logged. Prefix it with Site or your site’s name.
.tsx files directly in components/layouts/ are listed as layouts, so keep helpers in .ts files.