Blocks dans les Thèmes

Les templates de blocks vivent dans builder/block_templates/ et c'est ce qui transforme les données d'un block en HTML. Cette page vous montre exactement comment le builder câble les types de blocks dans les templates, et ce que votre thème ou un nouveau type de block peut attendre.

Le pipeline de résolution

Pour chaque block, le builder exécute une subroutine qui décide de la totalité de la sortie :

Les cycles sont attrapés en premier. Un block qui se re-référence lui-même rend un marqueur de commentaire au lieu d'une récursion infinie.
Recherche de langue avec repli : le block est récupéré par nom dans la langue de la page ; s'il manque, la version de la langue par défaut du même nom est utilisée à la place. Un block trouvé dans aucune langue devient un commentaire HTML « not found » ; il ne casse rien.
Les variables arrivent préparées. La ligne du block est passée à son template telle quelle : toutes les colonnes scalaires deviennent des variables de template, et son content_json est décodé en content_data (tableau ou hash, selon le type).
Les surcharges de placement l'emportent. Toute surcharge par placement (les overrides d'une affectation de stack, par exemple) fusionne par-dessus les champs stockés du block avant le rendu.
Le code de liaison conscient du type tourne. Certains types reçoivent du contexte supplémentaire avant que leur template tourne :
- page_list avec un parent posé publie un tableau pages des enfants sous ce parent, avec un en-tête auto-généré « Also in <category> » quand aucun n'est posé
- les blocks newsletter et form incorporent les champs du formulaire configuré et routent les soumissions vers le système de formulaires
- les blocks document chargent la fiche document référencée, avec en booléens quelles lignes de détail montrer (show_thumbnail, show_description, show_size, show_download_count, show_date)
- les blocks faq reçoivent un fragment de données structurées JSON-LD pré-calculé et échappé par sécurité
- les blocks columns et grid résolvent les shortcodes {{block:…}} à l'intérieur de leurs cellules pour que les blocks imbriqués y fonctionnent aussi
Les images s'enrichissent automatiquement. Si l'URL d'image du block correspond à un fichier média téléversé avec des dérivées responsives, image_srcset_jpg / image_srcset_webp arrivent dans le template préconstruits pour une sortie style <img srcset>.
Les erreurs restent piégées. Une erreur de rendu dans le propre template d'un block rend un commentaire « render error » au lieu d'avorter la page entière.

Où les blocks sont placés

Dans les corps des pages et posts : via le shortcode {{block:name}} résolu en ligne au moment du build ; tout ce que page.tt / post.tt / blog_index.tt / landing.tt de votre thème reçoit a déjà le HTML des blocks rendu.
Dans les stacks : les stacks composent plusieurs blocks en un fragment ; le fragment rend avec son propre id de conteneur et son id de layout (utilisé par les stacks dans les thèmes pour un stylage ciblé). Les stacks peuvent aussi contenir des stacks imbriqués, avec le même garde contre les cycles.
Vos templates voient du HTML imprimé, pas des objets block bruts : la var body qu'un template reçoit a déjà ses shortcodes remplacés.

À quoi ressemble un template de block

Chaque type de block a exactement un fichier Template Toolkit : builder/block_templates/<type>.tt (p. ex. cta.tt, gallery.tt). Ces fichiers sont livrés en dehors de votre thème : ils décrivent le balisage d'un block et sont les mêmes pour chaque thème, de sorte que votre thème les style par nom de classe au lieu de changer leur balisage.

Le template reçoit les variables de ligne du block plus content_data (JSON décodé), les variables de champs de formulaire quand un formulaire lié est configuré, et tout enrichissement spécifique au type ci-dessus qui s'applique.
page_list, document et les blocks « intelligents » similaires voient leurs données dépendantes matérialisées dans les variables de template, de sorte qu'un thème n'a qu'à imprimer des champs.

Le contrat CSS

Le _head.tt de votre thème doit styler les classes wrapper que les templates de chaque type de block émettent. Les tables de référence des blocks intégrés documentent la classe wrapper et inner de chaque type ; la feuille de style du thème par défaut les implémente exactement. Un block non stylé rend quand même son HTML ; il ne casse jamais le build, il a juste l'air inachevé dans le navigateur.

Ajouter un nouveau type de block

La recette de câblage : trois étapes, avec le registre Block Types comme gardien :

Enregistrez le slug du type sur l'écran Block Types. Cette table décide quels types sont valides pour create_block et le changement de type de block.
Créez builder/block_templates/<type>.tt : le template de rendu. Si vous prenez correctement en compte les variables et les règles d'enrichissement ci-dessus, vous êtes déjà presque au bout.
Créez templates/admin/blocks/types/<type>.html.ep : le partial de formulaire admin, qui remplit les champs plats et optionnellement un éditeur de ligne content_json.

Échappez les données contrôlées par l'utilisateur quand vous écrivez un template : HTML-échappez tout par défaut ; seuls les corps et les champs body à l'intérieur des données de contenu accordion/columns sont destinés à porter du HTML brut.

Mettre des blocks dans des templates de thème personnalisés

Quand vous rédigez un thème personnalisé, vous ne ré-intégrez pas les blocks ni n'invoquez le résolveur vous-même : le builder résout les shortcodes dans le texte du corps avant que votre template ne tourne. Votre thème se contente d'imprimer le body, qui arrive comme HTML déjà rendu. Si vous voulez des layouts pilotés par les blocks partout, utilisez les stacks : ce sont des séquences de blocks avec du contenu surchargeable et des règles d'affichage conditionnel, et ils rendent en une seule unité par affectation.