Single Directory Components : la brique de base du theming Drupal moderne
Ce que sont les Single Directory Components (SDC), comment un composant est organisé, la différence entre props et slots, et comment les utiliser depuis Twig, les render arrays et les constructeurs de pages.
Pendant des années, un « composant » Drupal était éparpillé dans le thème : un template Twig dans templates/, son CSS dans une bibliothèque déclarée dans *.libraries.yml, son JavaScript ailleurs, et aucune description des données attendues. Les Single Directory Components (SDC) règlent ce problème. Introduits dans Drupal 10.1 et intégrés à l'API du cœur depuis la 10.3, ils sont aujourd'hui la base du travail front-end dans Drupal, et des constructeurs de pages comme Canvas.
Un composant, un dossier
Un composant vit dans le dossier components/ d'un thème ou d'un module, avec tout ce dont il a besoin au même endroit :
components/
card/
card.component.yml # métadonnées et schéma (obligatoire)
card.twig # template (obligatoire)
card.css # chargé automatiquement quand le composant s'affiche
card.js # idem
README.md # documentation facultative
thumbnail.png # image d'aperçu facultative
Aucune bibliothèque à déclarer. Quand le composant est affiché, Drupal joint automatiquement son CSS et son JavaScript, et seulement sur les pages qui l'utilisent.
Le fichier de métadonnées
card.component.yml décrit le composant et ses entrées en JSON Schema :
$schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json
name: Card
status: stable
description: A teaser card with an image, a title and a link.
props:
type: object
required: [title]
properties:
title:
type: string
title: Title
url:
type: string
format: uri-reference
title: Link
variant:
type: string
enum: [default, highlighted]
slots:
body:
title: Body
Deux sortes d'entrées :
- Les props sont des données typées : chaînes, nombres, booléens, listes de valeurs, URL, tableaux. Le schéma les documente, et Drupal les valide quand les assertions sont activées (en développement) : un mauvais type échoue bruyamment au lieu d'afficher quelque chose de bizarre.
- Les slots acceptent du balisage libre : n'importe quel render array ou contenu Twig. Utilisez-les pour un contenu dont le composant ne maîtrise pas la structure (un corps de texte, une liste d'autres composants).
Le template les utilise comme n'importe quelle variable Twig :
<article{{ attributes.addClass('card', 'card--' ~ (variant ?? 'default')) }}>
<h3 class="card__title">
{% if url %}<a href="{{ url }}">{{ title }}</a>{% else %}{{ title }}{% endif %}
</h3>
<div class="card__body">
{% block body %}{% endblock %}
</div>
</article>
Utiliser un composant
Un composant s'identifie par fournisseur:nom, par exemple mytheme:card.
Depuis Twig, sans slot, avec include :
{{ include('mytheme:card', { title: node.label, url: url }, with_context = false) }}
Depuis Twig, avec des slots, avec embed, en remplissant les blocs :
{% embed 'mytheme:card' with { title: label } only %}
{% block body %}{{ content.field_summary }}{% endblock %}
{% endembed %}
Depuis PHP, avec l'élément de rendu component :
$build['card'] = [
'#type' => 'component',
'#component' => 'mytheme:card',
'#props' => ['title' => $title, 'url' => $url],
'#slots' => ['body' => $body_render_array],
];
Comme le composant possède son balisage et ses ressources, un template node--teaser.html.twig se réduit à un simple include qui associe les champs aux props.
Quelques détails utiles
- Remplacer un composant. Un thème peut remplacer un composant fourni par un module ou un thème de base avec la clé
replacesdans ses propres métadonnées, en gardant les mêmes props et slots. - Statut.
statusvautexperimental,stable,deprecatedouobsolete: cela indique aux autres développeurs (et aux outils) à quel point ils peuvent compter sur le composant. - Variantes. Les versions récentes du cœur permettent de déclarer des
variantsnommées dans les métadonnées, et l'élément de rendu accepte#variant. - Masquer dans les interfaces.
noUi: truegarde les composants internes hors des bibliothèques des constructeurs de pages. - Ajuster la bibliothèque.
libraryOverridesajoute des dépendances (par exemplecore/once) ou des ressources externes à la bibliothèque générée.
Pourquoi c'est important maintenant
SDC est ce qui permet au reste de l'écosystème de travailler avec votre thème :
- Drupal Canvas lit le schéma des composants pour construire le formulaire de chaque prop, et ne propose que les champs dont les données correspondent au type de la prop.
- Les outils à la Storybook et les bibliothèques de composants peuvent documenter et tester les composants isolément.
- Les thèmes contrib peuvent fournir des composants que d'autres thèmes réutilisent ou remplacent.
Conseils pour démarrer
- Commencez par de petits composants de présentation (bouton, carte, titre). Laissez la récupération des données à Drupal.
- Gardez des props simples et typées. Préférez une liste de valeurs (
enum) à une chaîne libre pour des options comme une variante ou une taille. - Utilisez les slots pour du contenu imbriqué, pas pour des données qu'une prop pourrait porter.
- Activez les assertions en local (
zend.assertions = 1) pour voir les erreurs de schéma pendant le développement. - Documentez chaque composant dans son
README.md. Six mois plus tard, c'est le premier fichier que vous ouvrirez.
Pour aller plus loin : la documentation SDC sur drupal.org.