Skip to Content

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:

  1. Path mapping: xtr_cms_slug_layout_configuration, for published pages only and not in preview.
  2. The item’s own layout: the page or item’s Layout field.
  3. The content type’s layout: xtr_cms_content_type_layout.
  4. The local fallback.

components/Layout.tsx then finds the component by name. If it can’t find one, it uses VdsLandingLayout.

Platform layouts

LayoutName in VisorPlaceholders
VdsLandingLayoutLanding pageHeader, Main, Footer
VdsContentLayoutContent page with sidebarHeader, Main, Left, Right, Footer
VdsArticleLayoutArticle pageHeader, 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.

Last updated on