Système de blocs

Vue d'ensemble

Les blocs sont les unités de construction de chaque page Cmssy. Dans le modèle headless, un bloc est un composant React dans votre propre dépôt Next.js, déclaré avec defineBlock et un schéma fields. L'admin Cmssy permet aux éditeurs de placer et configurer des instances de blocs ; votre site les affiche avec le SDK. Un bloc a trois parties :

• Schéma (fields) — les champs éditables affichés dans l'admin
• Composant — le composant React qui affiche le contenu
• Enregistrement — le bloc ajouté à votre tableau cmssy/blocks.ts

Définir un bloc

// blocks/hero/block.ts
import type { ComponentType } from "react";
import { defineBlock, fields } from "@cmssy/react";
import Component from "./src";

export const heroBlock = defineBlock({
  type: "hero",          // unique block type id, stored on each instance
  label: "Hero",
  component: Component as unknown as ComponentType<{ content: Record<string, unknown> }>,
  props: {
    heading: fields.singleLine({ label: "Heading" }),
    body: fields.richText({ label: "Body" }),
  },
});

Consultez Schéma & types de champs pour tous les types de champs, et Développement de blocs pour le guide complet.

Instances de blocs

Quand un éditeur ajoute votre bloc à une page, Cmssy stocke une instance de bloc :

{
  id: string;    // unique UUID for this instance
  type: string;  // matches your block's `type` (e.g. "hero")
  content: Record<string, unknown>;  // language-keyed field values
}

Le contenu est stocké par langue ({ en: {...}, pl: {...} }) ; le SDK résout la locale active avant de passer content à votre composant, vous lisez donc les champs directement.

Le composant, le context & les données

Votre composant reçoit { content, context, data } :

import type { CmssyBlockContext } from "@cmssy/react";

export default function Hero({ content, context }: {
  content: Record<string, unknown>;
  context?: CmssyBlockContext;
}) {
  const locale = context?.locale.current ?? "en";
  return <section><h1>{String(content.heading ?? "")}</h1></section>;
}

context porte locale ({ current, default, enabled }) et isPreview (true dans l'éditeur), plus forms, et — quand config.auth est défini — auth ({ isAuthenticated, member }) et workspace ({ id, slug }). Pour vos propres modèles ou enregistrements, récupérez les données avec createCmssyClient depuis @cmssy/react. Pour charger pendant le SSR (indexable, sans flash de chargement), donnez au bloc un loader — son résultat arrive dans la prop data. Voir Fonctionnalités avancées pour les deux.

Enregistrer les blocs

// cmssy/blocks.ts
import { heroBlock } from "@/blocks/hero/block";
export const blocks = [heroBlock];

Ce tableau est l'unique source de vérité : il pilote le rendu, et l'éditeur découvre le schéma de chaque bloc via le pont SDK, votre bloc apparaît donc dans le sélecteur de blocs de l'admin. Il n'y a pas d'étape séparée de build ou de publication — les blocs partent en production quand vous déployez votre application Next.js.

Blocs de layout

Le header, le footer et les autres zones partagées sont des blocs de layout — identiques aux blocs de page mais marqués avec layoutPositions (par ex. ["header"]) et rendus par CmssyServerLayout par position.

Internationalisation

Le contenu est stocké par langue dans le CMS et résolu à chaque requête. Le routage se fait par préfixe de chemin (/pl/*), la locale par défaut utilisant des URL propres. Lisez la locale active et les locales activées depuis context.locale.

Étapes suivantes

• Développement de blocs — guide complet : définir, composant, enregistrer, déployer
• Schéma & types de champs — tous les types de champs, repeaters, groupes
• Fonctionnalités avancées — blocs de layout, styles, loaders serveur