Regiony layoutu

Header i footer to nie jedyne miejsca, w których może żyć blok layoutu. Od cmssy-sdk 13 strona deklaruje swoje regiony w cmssy.config.ts, a edytor pokazuje w Layoutach dokładnie te. Sidebar, górny pasek, pasek cookies - cokolwiek Twoja aplikacja naprawdę montuje.

Bez deklaracji dostajesz header i footer, tak jak dotąd.

Deklarowanie regionów

// cmssy.config.ts
import { defineCmssyConfig, defineCmssyLayout } from "@cmssy/next";

export const layout = defineCmssyLayout({
  regions: [
    { id: "header", label: "Header" },
    { id: "sidebar", label: "Sidebar" },
    { id: "footer", label: "Footer" },
  ],
});

export const cmssy = defineCmssyConfig({
  org: process.env.CMSSY_ORG_SLUG,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,
  draftSecret: process.env.CMSSY_DRAFT_SECRET,
  apiUrl: process.env.CMSSY_API_URL,
  layout,
});

id zaczyna się literą lub cyfrą i dalej zawiera litery, cyfry, _ lub - (do 50 znaków). Id są unikalne, label to to, co widzi edytor, a layout ma najwyżej 20 regionów. Na wszystko inne defineCmssyLayout rzuca błędem przy starcie - literówka nie dociera do edytora.

Tablicę regions trzymaj inline w wywołaniu. Wyniesiona wcześniej do zmiennej rozszerza id do string i tracisz typowanie opisane niżej.

Typowane sloty

CmssyRegion<typeof layout> to unia zadeklarowanych id. Otypuj nią helper slotu, a slot dla regionu, którego nie zadeklarowałeś, nie skompiluje się:

import type { CmssyRegion } from "@cmssy/next";
import { cmssy, type layout } from "@/cmssy.config";

const slot = (position: CmssyRegion<typeof layout>) => (
  <CmssyLayoutSlot config={cmssy} blocks={blocks} position={position} path={path} />
);

{slot("header")}
<aside>{slot("sidebar")}</aside>
<main><CmssyPage {...props} /></main>
{slot("footer")}

layout importuj wyłącznie jako typ. Moduł konfiguracji czyta env serwera, a import wartości z komponentu klienckiego wciągnąłby go do bundla przeglądarki.

Slot pobiera layouty routowanej strony - decyduje path, a strona jak zwykle dziedziczy regiony po rodzicu. page podawaj tylko po to, by przypiąć slot do jednej strony niezależnie od route'a (w wariancie locale, który nie ma ścieżki, musisz).

Które bloki przyjmuje region

Blok zgłasza się do regionów przez layoutPositions. Edytor oferuje go tylko tam:

export const sidebarNavBlock = defineBlock({
  type: "sidebarNav",
  label: "Sidebar navigation",
  layoutPositions: ["sidebar"],
  component: SidebarNav,
  props: sidebarNavProps,
});

Blok bez layoutPositions jest blokiem strony i nigdy nie pojawia się w layoucie.

Ustawienia regionu

Region może mieć własne ustawienia, zadeklarowane tymi samymi builderami fields.*, których blok używa do swoich propsów. cmssy nie wymyśla żadnego z nich - header nie ma szerokości, a sidebar ma to, co mu zadeklarujesz:

import { fields } from "@cmssy/react";

export const layout = defineCmssyLayout({
  regions: [
    { id: "header", label: "Header" },
    {
      id: "sidebar",
      label: "Sidebar",
      settings: {
        width: fields.number({ label: "Width (rem)" }),
        sticky: fields.boolean({ label: "Sticky" }),
      },
    },
    { id: "footer", label: "Footer" },
  ],
});

Strona Layouty renderuje pod regionem formularz z tego schematu - region bez settings nie ma formularza. Wartości zapisują się per strona i dziedziczą w dół drzewa tak jak same bloki, a przy zapisie są walidowane względem Twojego schematu: nieznany klucz jest odrzucany.

API dostawcze zwraca je jako settings na grupie layoutu, typowane przez CmssyRegionSettings:

import type { CmssyRegionSettings } from "@cmssy/next";

type SidebarSettings = CmssyRegionSettings<typeof layout, "sidebar">;
// { width?: number; sticky?: boolean }

const sidebar = groups.find((g) => g.position === "sidebar")?.settings as SidebarSettings | null;

<aside className={sidebar?.sticky ? "sticky" : undefined} style={sidebar?.width ? { width: `${sidebar.width}rem` } : undefined}>
  {slot("sidebar")}
</aside>

Wymaga cmssy-sdk 14. Na 13 zapytanie dostawcze wciąż prosi o stary, sztywny kształt ustawień i pada na aktualnym API - zaktualizuj przed deployem.

Skąd edytor o nich wie

W Next createCmssyPage i createCmssyEditPage same przekazują regiony do edytora. W Astro i React Routerze loadCmssyPage / createCmssyLoader zwracają layoutRegions - przekaż je do CmssyEditor jako edit={{ editorOrigin, layoutRegions }}. API dostawcze zwraca grupy layoutu pod Twoimi id, więc groups.find(g => g.position === "sidebar") działa tak, jak się spodziewasz.

Usuwanie regionu

Wytnij region z regions, a jego bloki nie znikają. Edytor zostawia kartę, oznacza ją jako niemontowaną przez stronę i pozwala Ci samemu przenieść albo usunąć bloki. Nic nie znika ze strony dlatego, że deploy zmienił plik konfiguracji.

Wymaga TypeScript 5.0 lub nowszego (typowanie opiera się na parametrach typu const). Zobacz Layouty dla dziedziczenia i podziału public/edit oraz przewodnik migracji sdk v12-to-v13 dla zmiany nazwy z LayoutPosition.