Accueil Blog Comment utiliser Single Directory Components (SDC) avec Drupal 10 ?

Comment utiliser Single Directory Components (SDC) avec Drupal 10 ?

23 mai 2024

Comment s’affranchir du système de templating habituel de Drupal pour faciliter l’organisation du front ? Connaissez-vous le module Single Directory Components ?

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 :

Pour les versions antérieures à Drupal 10.3, le module Single Directory Components doit être activé.
Vous devez avoir un thème ou un module auquel vous souhaitez ajouter des composants.

Sur cette photo, nous voyons un développeur saisir du code sur son ordinateur

Quels sont les avantages de Single Directory Components ?

Pourquoi utiliser Single Directory Components de Drupal dans un projet Web ? J’ai listé pour vous les avantages de ce module.

Organisation des fichiers de rendu : En regroupant tous les fichiers nécessaires à la création et au rendu dans un seul répertoire, on facilite la tâche du développeur front. Il n’est plus nécessaire de naviguer d’un bout à l’autre de l’arborescence des fichiers pour retrouver les templates de rendu d’un élément, les fichiers d’assets (CSS/JS) potentiellement chargés avec, et comprendre l’origine des variables utilisées dans le template. En résumé, le développeur front n’a plus forcément besoin de connaître le système de templating de Drupal.
Création automatique de librairies : Par défaut, SDC vérifie l’existence de fichiers my-component.css et my-component.js. Si ces fichiers existent, Single Directory Components en génère automatiquement une librairie.
Réutilisation : Les composants sont définis pour être modulaires et réutilisables, ce qui facilite grandement leur intégration dans différents templates.
Cohérence : Réutiliser les composants permet d’assurer une meilleure cohérence au rendu.
Évolutivité : Faciliter la création et l’ajout de composants au rendu global contribue à la capacité d’évolution d’un site Web.
Facilitation des tests : Le fait que les composants puissent se comporter comme des briques indépendantes simplifie l’identification de bugs.

Création et intégration du premier composant

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.

Les étapes de création de notre premier composant

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.

Capture d'écran du code pour créer le fichier node_content.component.yml

Dans notre exemple, le composant est notamment constitué des propriétés suivantes :

name, le « Human-name » du composant ;
props, l’objet contenant des propriétés (« properties »), en sachant que chaque propriété a une structure et un type bien définis comme une valeur texte, un booléen, etc. ;
slots, qui répertorie les items du composant n’ayant pas une structure définie (ils peuvent par exemple contenir d’autres composants, du code HTML, un bloc de rendu Twig).

3. Le second fichier obligatoire est le fichier Twig de rendu du composant. Ici, nous créons un fichier node_content.twig.

Capture d'écran du code pour créer le 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 :

Capture d'écran du code pour créer le fichier node_content.css

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

Utilisation du composant

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).

Capture d'écran du code pour intégrer notre composant dans le fichier de template node.html.twig

💡 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.

Capture d'écran montrant le résultat de notre node_content et du code hmtl associé

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.

Avec JavaScript, dynamiser votre 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.

Capture d'écran du code pour ajouter un bouton à notre fichier node_content.twig

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.

Capture d'écran du code pour illustrer l'ajout d'une librairie dans notre fichier node_content.component.yml

Ensuite, nous pouvons créer notre fichier node_content.js comme suit :

Capture d'écran du code pour créer le fichier node_content.js

Pour terminer, vidons à nouveau les caches et observons le résultat après quelques clics sur notre bouton.

Sur cette capture d'écran, nous voyons 4 résultats. Le seul changement est la couleur de fond : rouge, jaune, violette, vert

Et voilà ! Notre composant est devenu dynamique et chaque utilisateur est libre de lire sa page dans la couleur de son choix. 🙂

Pour aller plus loin, imbrication de composants

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 :

l’ajout de composants au sein d’un autre composant ;
une architecture du dossier components souple qui permet d’imbriquer les dossiers de déclaration de composants (ex. components/my_parent_component/my_child_component).

Adaptons cela à notre composant node_content. Nous allons donc :

transformer notre bouton de changement de couleur en composant switch_color_button ;
insérer ce nouveau composant dans notre composant node_content.

Création de notre composant `switch_color_button`

Pour 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.

Capture d'écran du code pour créer 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).

Mise à jour du composant node_content

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.

Capture d'écran du code pour modifier le schéma de notre composant node_content dans le fichier node_content.component.yml

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).

Capture d'écran du code pour modifier le template node-content.yml

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