Concepts de base du composant d’annuaire unique dans Drupal

Qu’est-ce qu’un composant ?

Dans développement webun composant est une partie d’une page Web ou d’une application modulaire et réutilisable, avec une fonctionnalité ou un objectif spécifique. C’est comme un élément de base qui peut être utilisé pour créer des interfaces complexes.

Les composants sont constitués de Code HTML, CSS et JavaScriptet peut être facilement personnalisé et réutilisé sur plusieurs pages ou applications. Des exemples de composants incluent les menus de navigation, les formulaires, les curseurs et les boutons.

Qu’est-ce qu’un composant d’annuaire unique ?

Les composants à répertoire unique (souvent abrégés en SDC) sont Drupal implémentation des composants par le noyau. Au sein de SDC, tous les fichiers nécessaires au rendu du composant sont regroupés dans un seul répertoire (d’où le nom !). Cela inclut Twig, YAML et CSS, JavaScript, etc. en option. SDC générera automatiquement une bibliothèque pour charger CSS/JS lorsque le modèle est invoqué.

Pourquoi un composant d’annuaire unique introduit dans Drupal ?

La fonctionnalité SDC a été introduite dans Drupal 9 pour répondre aux défis et limites spécifiques des thèmes traditionnels et du développement basé sur des composants. Voici quelques raisons :

1. Paradigme de développement moderne

• Tendance vers une architecture basée sur les composants : Les frameworks frontaux modernes tels que React, Vue et Angular organisent les éléments de l’interface utilisateur en tant que composants autonomes. SDC apporte à Drupal cette approche de développement basée sur les composants, où tous les fichiers associés (Twig, CSS, JavaScript et configuration) pour un composant spécifique sont regroupés dans un seul répertoire.

2. Améliorer l’organisation du code

• Problèmes liés à l’approche traditionnelle : Les fichiers d’un seul composant sont souvent dispersés dans plusieurs répertoires : modèles Twig dans /templates. CSS dans /css ou /scss. JavaScript dans /js. Cette dispersion rend plus difficile la gestion, le débogage et la réutilisation des composants.
• Solution SDC : En regroupant tout dans un seul répertoire, les développeurs peuvent se concentrer sur un dossier autonome pour une fonctionnalité ou un élément d’interface utilisateur spécifique.

3. Simplifiez la réutilisabilité

• Défi traditionnel : La réutilisation de composants entre thèmes ou modules nécessite souvent la duplication de modèles, de styles et de logique. L’extension ou le remplacement de composants peuvent entraîner des incohérences.
• Solution SDC : Les composants sont autonomes et modulaires, ce qui les rend plus faciles à réutiliser ou à remplacer dans différents thèmes ou modules

4. Prise en charge des systèmes de conception

• Défi traditionnel : Les systèmes de conception nécessitent une approche structurée des composants. Les fichiers dispersés rendent plus difficile le respect de la cohérence ou l’adaptation aux flux de travail modernes comme l’utilisation de Storybook.
• Solution SDC : SDC aligne Drupal sur les systèmes de conception en fournissant une approche structurée et standardisée de la création de composants. Il facilite l’intégration avec des outils tels que Storybook pour les bibliothèques de composants.

5. Alignement sur les normes modernes

• Garder Drupal compétitif : Avec SDC, Drupal s’aligne sur les CMS et les frameworks modernes qui donnent la priorité à l’expérience et à la modularité des développeurs (par exemple, l’éditeur de blocs WordPress, les composants React). Il modernise l’expérience de développement, attirant les développeurs familiers avec les architectures basées sur des composants.

6. Meilleur support multilingue et thématique

• • Les composants de SDC peuvent exploiter plus efficacement les systèmes de traduction et de création de thèmes de Drupal.
  • Les traductions sont gérées dans des modèles Twig avec des fonctions t().
  • Les composants spécifiques à un thème peuvent remplacer SDC sans interrompre les fonctionnalités de base.

Avantages de l’utilisation de SDC

L’utilisation de SDC présente de nombreux avantages

• Organisation: Le regroupement de tout le code nécessaire dans un seul répertoire facilite la recherche et le passage entre les fichiers pertinents.
• Automatique création de bibliothèque : SDC recherchera automatiquement my-component.css et my-component.js et les ajoutera à une bibliothèque générée automatiquement s’il est trouvé. Vous pouvez spécifier des actifs et des dépendances supplémentaires dans le fichier YML du composant si nécessaire.
• Réutilisabilité: Les composants sont conçus pour être modulaires et réutilisables, ce qui signifie qu’ils peuvent être facilement intégrés dans plusieurs pages ou applications.
• Cohérence: En utilisant des composants, les développeurs peuvent garantir que leurs pages Web ou applications ont une apparence cohérente dans l’ensemble.
• Évolutivité: Les composants peuvent contribuer à rendre les pages Web ou les applications plus évolutives, car ils peuvent être facilement ajoutés ou supprimés selon les besoins.
• Essai: Les composants peuvent souvent être testés de manière isolée, ce qui peut faciliter l’identification et la correction des bogues ou des problèmes.
• Collaboration: L’utilisation de composants peut faciliter la collaboration des équipes de développeurs, car ils peuvent partager et réutiliser des composants dans différents projets.

Comment travailler avec SDC ?

Pour développer la DDC, ce qu’il faut savoir

• Si vous utilisez Drupal9 il faut installer le module de contribution l’utilisation de cette commande composer nécessite ‘drupal/sdc:^1.0’.
• Pour Drupal 10.1 et les versions de base ultérieures, le module Single Directory Component (SDC) est inclus dans le noyau.
• Activez le module Composants d’annuaire unique.
• Dans Drupal 10.3 Les composants à répertoire unique sont devenus une partie du système de rendu.
• Désactivez l’agrégation CSS et JS dans l’interface utilisateur d’administration Drupal à des fins de développement.
• Activez le mode de développement Twig et désactivez la mise en cache.

Créer un composant

1. Créez un nouveau répertoire appelé composants/ dans le répertoire de votre thème ou module personnalisé.
2. Créez un nouveau répertoire dans le répertoire composants/ avec le nom de votre nouveau composant (ex – carrousel).
3. Créez deux nouveaux fichiers dans ce répertoire
   1. Un fichier twig avec le nom de votre composant (ex carousel.twig)
   2. Un fichier YAML avec l’extension *.component.yml qui porte le nom de votre composant (ex carousel.component.yml).
4. Le CSS et le JavaScript doivent porter le nom du composant (par exemple, carousel.css et carousel.js) pour les charger automatiquement.
5. Vous pouvez charger des styles, des scripts et des dépendances supplémentaires à l’aide de la clé libraryOverrides dans votre

Structure de répertoire finale

A titre d’exemple, nous créons un composant dans un module personnalisé.

|- web/modules/custom/my-module
    |- components
        |- my-component
            |- my-component.twig (required)
            |- my-component.component.yml (required)
            |- README.md (optional)
            |- thumbnail.png  (optional)
            |- my-component.js
            |- my-component.css
            |- assets (optional)
                |- img1.png

Commande Drush avec SDC

drush generate single_directory_component

Remarque – Version minimale de Drush – Drush 12 ou version ultérieure

Quelques terminologies courantes avant de plonger dans le fichier *.component.yml

Dans le cadre Drupal Single Directory Component (SDC), les données peuvent être transmises à un composant en utilisant deux méthodes : « accessoires » (abréviation de « propriétés ») et « emplacements ». Ces concepts proviennent de frameworks JavaScript comme Vue et React, incarnant la notion de fourniture ou d’introduction de données dans un composant.

• Accessoires adhérer à une structure spécifiée pour transmettre les données au composant, en utilisant le format JavaScript Object Notation (JSON) avec des paires clé-valeur.
• Machines à sous gérer des données non structurées, englobant des scénarios tels que des composants imbriqués, des blocs Twig ou du balisage HTML. Contrairement aux accessoires, les emplacements ne nécessitent pas de schéma JSON avec des paires clé-valeur et ne sont pas limités par les types de données JSON.

Exploration du fichier composant.yml – Métadonnées

La présence du *.composant.yml le dossier est important ; en son absence, Drupal reste dans l’ignorance de l’existence de votre composant. Ce fichier doit être créé dans le répertoire du composant. Passons en revue la définition du fichier *.component.yml.

Exemple de fichier YAML de composant

Ici, nous créons un composant carrousel dans un module personnalisé ayant des accessoires comme titre et curseur.

Sur le chemin ci-dessous web/modules/custom/my-module/components/carousel.component.yml

# This is so your IDE knows about the syntax for fixes and autocomplete.
$schema: 'https://git.drupalcode.org/project/drupal/-/raw/10.1.x/core/modules/sdc/src/metadata.schema.json'

# The human readable name.
name: Carousel

# Status can be: "experimental", "stable", "deprecated", "obsolete".
status: stable

props:
  type: object
  properties:
    title:
      type: string
      title: Section Title
      description: The title shown above the carousel (e.g. "popular courses")
    slides:
      type: array
      title: Carousel Slides
      items:
        type: object
        properties:
          image:
            type: object
            required:
              - url
              - alt
            properties:
              url:
                type: string
                title: Image URL
              alt:
                type: string
                title: Image Alt Text
          title:
            type: string
            title: Slide Title
          description:
            type: string
            title: Slide Description
  required:
    - title
    - slides

Rendre un composant

Pour utiliser un composant dans un modèle *.html.twig, utilisez les fonctions d’intégration ou d’inclusion intégrées de Twig.

• Utiliser inclure(): Utilisez la fonction Twig include() s’il n’y a pas d’emplacements ou de propriétés HTML arbitraires et que les données suivent toutes une structure définie. Exemple –

  {{ include('my-module:carousel',{ props:{
      title: 'Carousel',
      slides: [
        {
          image: {
            url: 'https://images.unsplash.com/photo-1508766206392-8bd5cf550d1c',
            alt: 'Internal medicine course image'
          },
          title: 'internal medicine i',
          description: 'Explore the intricacies of diagnosing and treating adult diseases! From common ailments to complex medical conditions, gain a comprehensive understanding of internal medicine.'
        }
      ]
    }}) }}
  

• Utiliser {% intégrer %} : Utilisez une balise Twig {% embed %} si vous devez remplir des emplacements.
  Exemple de fonction d’intégration.
  Ici, les données seront l’objet dynamique du curseur et le titre du curseur sera passé comme emplacement

  {% embed 'my-module:carousel' with { props:{
      slides: data
    }}
  %}
    {% block heading %}
      {{ slider_title }}
    {% endblock %}
  {% endembed %}

Remplacer un composant

Seuls les thèmes peuvent remplacer les composants, et il y a deux conditions importantes pour ce faire :

1. Ajouter un remplace clé en haut du fichier *.component.yml que vous souhaitez remplacer

   name: Override existing Carousel
   replaces: my-custom.carousel
   

2. Le composant doit avoir un schéma défini.

Il est important de noter que les modules ne peuvent pas remplacer les composants et que seuls les composants ayant un schéma défini peuvent en remplacer et être remplacés par d’autres.

Conclusion

Ce blog vous aidera à créer un Composant de base d’annuaire unique dans votre Application Drupal. SDC vous permet de définir des schémas dans le fichier YML, permettant aux modules contribués et au noyau Drupal de générer automatiquement des formulaires pour la saisie de données. Cela nous permet d’ajouter des composants directement à l’aide d’outils tels que Layout Builder et CKEditor sans avoir besoin d’entités personnalisées.

VOUS TROUVEZ CECI UTILE ? PARTAGEZ-LE