Single Directory Components (ou SDC) est apparu en juin 2023 en tant que module expérimental de Drupal 10.1.0. En mars 2024, il a été officiellement intégré au core de Drupal, et avec Drupal 10.3, SDC devient une partie intégrante du système de rendu.
Mais pourquoi ce module ? Pour faire simple, son but est de faciliter le rendu du front d'un site Web par la création de composants ("components" - partie d'une page Web qui est modulaire et réutilisable – ex : un bouton) dont l'entièreté des fichiers nécessaires à leur création et à leur rendu est rassemblée dans un répertoire unique propre à chaque composant ("Single directory").
Dans cet article, je reviendrai sur les avantages du module Single Directory Components et sur les moyens de le mettre en place dans Drupal 10. Mais avant de commencer, voici 2 prérequis :
Pourquoi utiliser Single Directory Components de Drupal dans un projet Web ? J’ai listé pour vous les avantages de ce module.
my-component.css et my-component.js. Si ces fichiers existent, Single Directory Components en génère automatiquement une librairie.Pour bien comprendre le fonctionnement du module Single Directory Components, passons à la pratique. Dans cette partie, découvrez les étapes de création du composant et les bonnes pratiques pour le dynamiser avec JavaScript. C’est parti.
Pour vous expliquer le fonctionnement de ce module, nous allons maintenant créer un composant pour rendre le contenu d’un node avec une couleur de fond spécifique.
1. La première étape est de se positionner dans le module ou thème où l’on souhaite créer le composant. Ici, nous utiliserons le thème custom « My theme ». Nous y créons le dossier components/node_content.
2. Ensuite, dans ce dossier, nous créons le fichier node_content.component.yml. Ce dernier est obligatoire pour permettre la découverte du composant. Il définit le schéma de notre composant.
Dans notre exemple, le composant est notamment constitué des propriétés suivantes :
3. Le second fichier obligatoire est le fichier Twig de rendu du composant. Ici, nous créons un fichier node_content.twig.
Dans ce fichier, nous retrouvons le nom des propriétés et slots définis dans le fichier node_content.component.yml.
4. En avant dernière étape, nous créons le fichier node_content.css dans lequel nous définissons les propriétés de style suivantes :
5. Enfin, vidons les caches du site. Notre composant est prêt à l’emploi et notre arborescence est la suivante :
my_theme
| - components
| - node_content
| - node_content.component.yml (obligatoire)
| - node_content.twig (obligatore)
| - node_content.css
Pour utiliser notre composant, nous allons l’insérer dans un template Twig via la fonction embed. Intégrons notre composant dans le fichier de template node.html.twig. Pour importer un composant, il faut utiliser le couple key:id qui le définit (key est le thème/module où le composant est défini et id est son machine_name).
💡 Pour info, à la place de la fonction embed, vous pouvez utiliser la fonction include(). Toutefois, celle-ci n’est recommandée que lorsque le composant ne contient pas de slots.
Observons maintenant le résultat.
Sur ces deux captures, nous pouvons observer que le contenu de notre node est maintenant rendu par le biais de notre composant. Si nous activons l’outil de debug Twig, nous pouvons constater que dans le code HTML, c’est notre composant qui est utilisé.
Maintenant que le rendu de nos nodes passe par un seul composant, nous pouvons tout à fait imaginer vouloir rendre le contenu des nodes de type « article » en vert. Il suffit alors de créer le fichier de template node--article.html.twig à partir de node.hmtl.twig et de changer la propriété « color » de notre composant.
Allons encore un peu plus loin dans l’exemple. Nous avons des nodes dont nous pouvons définir la couleur de fond. Et si nous donnions la possibilité à l’utilisateur de changer la couleur de fond ? Pour ce faire, nous rajoutons un bouton cliquable dans notre composant, et via l’intégration de la librairie automatique, nous renseignons le JavaScript nécessaire.
Maintenant, reprenons notre fichier node_content.twig et ajoutons le bouton au fichier existant.
L’étape suivante consiste à créer le fichier node_content.js. Toutefois, au lieu d’écrire du code JavaScript pur, nous pouvons bénéficier de l’environnement de Drupal en utilisant les librairies : core/drupal, core/jquery et core/once. Pour cela, comme pour une librairie classique, il faut déclarer des dépendances. Mais comment faire pour une librairie auto-générée ?
La réponse est simple : il suffit d’utiliser la propriété libraryOverrides dans notre fichier de définition node_content.component.yml.
Ensuite, nous pouvons créer notre fichier node_content.js comme suit :
Pour terminer, vidons à nouveau les caches et observons le résultat après quelques clics sur notre bouton.
Et voilà ! Notre composant est devenu dynamique et chaque utilisateur est libre de lire sa page dans la couleur de son choix. 🙂
Reprenons donc notre exemple. Ce dernier est simple, fonctionnel et parfaitement compréhensible. Imaginons maintenant qu’en plus de notre bouton, nous souhaitons ajouter une bannière image, un CTA, une zone de texte, etc. Cela va vite complexifier notre composant. Alors, comment faire pour rester simple ?
La solution que je vous propose est d’utiliser l’approche atomic design (i.e. décomposer notre élément final en plusieurs petits éléments simples et basiques (des atomes) – nous pouvons comparer cela à un célèbre jeu de construction en briques où chaque brique a une forme simple et une fonction limitée (mais une fois ces briques assemblées, elles peuvent donner des constructions complexes)).
Single Directory Components (SDC) permet de faire de l’atomic design en autorisant :
components/my_parent_component/my_child_component).Adaptons cela à notre composant node_content. Nous allons donc :
switch_color_button ;node_content.switch_color_buttonPour commencer, notre nouveau composant étant considéré comme un enfant du composant node_content, nous créons le nouveau dossier my_theme/components/node_content/switch_color_button/.
Dans ce nouveau dossier, nous déclarons notre composant via le fichier switch_color_button.component.yml.
Ensuite, créons le fichier twig switch_color_button.twig.
Enfin, déplaçons le fichier node_content.js vers switch_color_button/switch_color_button.js (le script étant lié au bouton, autant l’associer à ce composant).
Maintenant, modifions le schéma de notre composant node_content dans node_content.component.yml, en rajoutant un slot « switch_color_button » et en supprimant les dépendances aux librairies JavaScript.
Ensuite, modifions le template node-content.yml pour y rajouter le slot « switch_color_button » qui accueillera notre composant enfant switch_color_button. Nous pouvons transmettre les propriétés souhaitées à ce dernier. Nous noterons également l’utilisation de la fonction twig include() plutôt que embed() (conseillé si l’on n’utilise pas de slot dans notre composant).
Nous obtenons donc maintenant l’arborescence suivante :
my_theme
| - components
| - node_content
| - node_content.component.yml (obligatoire)
| - node_content.twig (obligatore)
| - node_content.css
| - switch_color_button
| - switch_color_button.component.yml (obligatoire)
| - switch_color_button.twig (obligatoire)
| - switch_color_button.js
Pour finir, vidons le cache Drupal. Si tout s’est bien passé, le rendu est exactement le même que précédemment. Mais notre architecture est maintenant optimisée pour faciliter l’évolution de nos composants. 🙂
Voilà, nous avons terminé. Vous savez maintenant créer un composant, le rendre dynamique en utilisant JavaScript, et imbriquer plusieurs composants. J’espère que cet article vous a été utile. Pour poursuivre votre lecture, je vous recommande deux autres articles de notre blog technique :
Crédit photo : scyther5