Theme SDK
Rendez les pages publiques avec des templates TSX ou des documents de blocs.
Sur cette page
Le runtime de distribution
Un thème empaqueté exporte une factory recevant ThemeRuntime : createElement, Fragment, defineTheme, Blocks, Menu, SiteLayout et ContentFields. Les dépendances JavaScript statiques sont assemblées au packaging ; la factory conserve le contexte React fourni par le CMS.
import type { ThemeRuntime } from "@bracten/sdk/theme";
export default function theme(runtime: ThemeRuntime) {
const { SiteLayout, Blocks } = runtime;
return runtime.defineTheme({
id: "agency.example", name: "Example", version: "0.1.0",
parent: "official.starter",
templates: {
page: (context) => (
<SiteLayout context={context}>
<h1>{context.content?.title}</h1>
{context.content && (
<Blocks document={context.content.document} context={context} />
)}
</SiteLayout>
),
},
});
}theme:create génère le projet TypeScript et la configuration JSX. themes/minimal-child fournit aussi une référence complète avec manifest, feuille CSS et packaging ; ce fragment seul n’est pas un package installable.
TemplateContext
| Valeur | Rôle |
|---|---|
| site, menu | Réglages et menu principal, conservé pour compatibilité. |
| menus, menuLabels | Menus nommés et libellés accessibles, facultatifs dans le type. |
| messages, interfaceLocale | Catalogue et langue des libellés publics. |
| content, contentType | Contenu courant ou null et son schéma. |
| collection, search, path, archiveTitle | Résultats paginés et contexte de la route publique. |
| parts, syncedPatterns, themeSettings | Parties, compositions synchronisées et réglages résolus. |
| terms, fieldTerms, references, parent | Termes et références autorisées, y compris chemins de champs imbriqués. |
| media | Dictionnaire des médias des champs, avec titre indépendant, texte alternatif, légende, MIME, dimensions et variantes. |
ContentFields rend les valeurs structurées, médias, PDF, termes et relations résolues ; userRelation reste omis du rendu public. Une cible privée ou inaccessible ne doit pas être lue directement à partir de son identifiant. Passez context aux blocs pour préserver compositions et données dynamiques.
MediaEntry.title peut être vide. Un thème peut utiliser explicitement context.media[id].title, avec l’échappement habituel de React ; les composants natifs n’en déduisent ni un texte alternatif, ni une légende, ni un attribut HTML title. Le nom du fichier et ses URL restent indépendants.
Résolution et héritage
Les noms reconnus sont index, home, page, post, archive, taxonomy, search, 404, type_<identifiant>, taxonomy_<identifiant> et les noms de terme produits par termTemplateName. Un template propre au terme précède celui de sa taxonomie, puis taxonomy, archive et index. post peut revenir à page puis index. Les personnalisations enregistrées peuvent remplacer les documents distribués.
Un enfant peut remplacer un template TSX par un document ou inversement. La chaîne est limitée à huit niveaux et exige un index effectif. Parents absents, incompatibles ou circulaires sont refusés. Les CSS parents précèdent celui de l’enfant.
Documents, édition et mises à jour
ThemeDefinition accepte documents, parts, patterns, tokens et settings. L’éditeur de site gère aperçu, copies privées, récupération, révisions et retour à la source. Les compositions synchronisées conservent une copie de secours.
Le bloc navigation utilise props.menu, primary par défaut, et un props.label accessible facultatif. Les liens vers des contenus ou termes suivent leur adresse et sont filtrés selon leur visibilité. Un menu absent rend une navigation vide ; il ne se replie pas sur un autre menu.
defaultMessages associe explicitement des blocs de documents distribués à des clés du catalogue de langue. Starter utilise ce mécanisme pour ses textes par défaut. Une surcharge personnalisée reste un contenu de l’utilisateur, même si son texte ressemble au texte initial ; elle n’est pas traduite implicitement. Le rendu public suit la langue du site ou du contenu, pas la préférence du compte connecté.
Les réglages et surcharges appartiennent au thème actif ; les schémas de réglages des parents ne sont pas fusionnés automatiquement. La mise à jour locale prépare une sauvegarde, contrôle l’héritage et conserve les surcharges. Un rollback rétablit un package antérieur compatible, sans annuler toutes les données de l’instance. Consultez docs/themes.md pour ces garanties.