Drupal Paragraphs tutorial, partie 1 : planifier l'architecture et les types de base

13.07.2026

Ceci est la partie 1 d’un guide en deux parties pour construire un site corporate basé sur des composants avec Drupal Paragraphs. À la fin de la série, vous aurez une bibliothèque de 10 à 12 types de paragraphes universels avec variantes de style, layouts responsives et contrôles d’espacement adaptés aux rédacteurs.

Un Drupal Paragraphs tutorial est facile à trouver pour les bases - installer le module, créer un type, ajouter un champ. Ce qui manque le plus souvent, c’est un guide pour construire une bibliothèque de composants cohérente : un petit ensemble universel de types de paragraphes que les rédacteurs aiment et que les développeurs peuvent maintenir pendant des années. C’est ce que cette série livre ; la partie 1 pose les fondations : planifier l’architecture, configurer correctement le module et construire vos trois premiers types de paragraphes avec du code concret.

Ce guide suppose Drupal 10 ou 11 et une connaissance de base du module Drupal Paragraphs. Vous n’avez pas besoin d’être expert - mais vous devez être à l’aise avec la création de champs et l’édition de templates Twig. Si votre configuration actuelle frustre les rédacteurs plus qu’elle ne les aide, notre article Drupal Paragraphs : d’inutilisable à adapté aux rédacteurs explique ce qui sépare une implémentation cassée d’une qui fonctionne en production.

Dans cet article :

Que construirez-vous dans cette série Drupal Paragraphs tutorial ?
Comment planifier une bibliothèque de composants réutilisables ?
Comment configurer les fondations Paragraphs ?
Comment construire vos trois premiers types de paragraphes Drupal ?
Comment tester et valider l’expérience rédacteur ?

Que construirez-vous dans cette série Drupal Paragraphs tutorial ?

L’objectif n’est pas un empilement de sections uniques, mais une bibliothèque de composants polyvalente - un petit ensemble de types de paragraphes qui combine pour produire la plupart des pages d’un site corporate. Sur les deux parties, vous construirez :

Partie 1 (cet article) : l’architecture, le socle module et trois types de paragraphes centraux - Hero, Texte + Image et Feature Grid.
Partie 2 : variantes de couleur et de style, layouts responsives dédiés, espacement contrôlé par les rédacteurs, champs conditionnels, UX admin, performance et maintenance à long terme - plus les types restants (CTA, Cards, Testimonial, FAQ, Stats).

Le principe directeur est la réutilisabilité. Une bibliothèque bien conçue est petite - 10 à 15 blocs réutilisables - et couvre pourtant une large gamme de layouts, car les composants sont assez polyvalents pour se combiner différemment. Cette mentalité - penser en composants plutôt qu’en templates de page - est le même changement que nous décrivons dans apprendre aux clients à penser en composants.

Lisez aussi : création de contenu flexible et facile avec le module Drupal Paragraphs et mode d’affichage des paragraphes - révision d’un module pour Drupal.

Comment planifier une bibliothèque de composants réutilisables ?

Avant d’installer quoi que ce soit, décidez de ce que vous devez vraiment construire. Les bibliothèques de composants échouent quand elles deviennent un cimetière de types spécifiques à une page - planifiez la réutilisation dès le départ.

Commencez par un audit. Listez les pages qu’un site corporate typique nécessite : page d’accueil, pages produit ou service, à propos, landing pages, contact, actualités. Puis, au lieu de designer chaque page, décomposez-la en sections récurrentes. Vous remarquerez vite les mêmes motifs - un hero en haut, des blocs texte-image alternés, une grille de fonctionnalités, un appel à l’action, des cartes.

Ces motifs récurrents sont vos composants. Un minimum viable solide pour un site corporate :

Hero - bannière d’ouverture de page avec titre, sous-titre, image et appel à l’action.
Texte + Image - titre et corps à côté d’une image, à gauche ou à droite.
Feature Grid - titre plus un ensemble d’éléments répétés dans un nombre de colonnes configurable.
Bloc CTA - section d’appel à l’action focalisée.
Cards - rangée de cartes liées pour navigation ou highlights.
Testimonial - citation avec attribution.
FAQ - liste de paires question-réponse.
Stats / Numbers - rangée de chiffres clés.
Content List - listing dynamique de contenu lié.
Contact Form - formulaire intégré.

Terminez la planification avec une matrice de paragraphes simple : un tableau qui mappe quels types apparaissent sur quels types de page. Cela valide que votre ensemble est vraiment universel - si un type n’apparaît que sur une page, questionnez s’il appartient à la bibliothèque.

Comment configurer les fondations Paragraphs ?

Avec le plan en main, installez le module et posez des conventions que chaque type de paragraphe suivra.

Installez via Composer et activez :

composer require drupal/paragraphs
drush en paragraphs -y

Ensuite, ajoutez un champ de référence paragraphs au type de contenu qui hébergera vos composants - typiquement un type landing page ou basic page. Le type de champ est Entity reference revisions, que Paragraphs utilise pour les révisions :

# field.field.node.landing_page.field_components (illustratif)
field_name: field_components
entity_type: node
bundle: landing_page
label: 'Components'
field_type: entity_reference_revisions
settings:
  handler: 'default:paragraph'

Sur l’affichage formulaire du champ, utilisez le widget Paragraphs (stable) et réglez le « Add mode » sur bouton ou menu déroulant pour un menu de composants clair. Pour une édition quotidienne plus rapide, des outils comme Geysir peuvent améliorer l’expérience admin une fois la bibliothèque agrandie.

Note sur le concept de « type de base » : Drupal Paragraphs ne supporte pas l’héritage de type, il n’y a donc pas de type de base littéral à étendre. En pratique, « base » signifie deux choses - une convention de nommage de champs appliquée de façon cohérente (par exemple, tout type avec un titre utilise field_heading, tout type avec un style utilise field_style), et, pour les réglages transversaux, un plugin Paragraphs behavior. Les behaviors sont le moyen d’ajouter un réglage partagé (variante de style ou espacement) à plusieurs types ; nous les introduisons dans la partie 2 de cette série Drupal Paragraphs tutorial. Pour l’instant, adoptez la convention de nommage - la cohérence paie dans chaque template et feuille de style.

Décidez votre stratégie de champs dès le départ :

gardez les champs obligatoires au minimum dont un composant a réellement besoin ;
rendez tout le reste optionnel et designez les templates pour gérer les champs vides ;
utilisez des types et noms de champs cohérents entre composants ;
ordonnez les champs dans le formulaire par fréquence d’usage - les plus utilisés en premier.

Comment construire vos trois premiers types de paragraphes Drupal ?

Créez maintenant trois types qui couvrent les motifs centraux : une bannière simple (Hero), un bloc deux colonnes (Texte + Image) et une grille d’éléments répétés (Feature Grid). Chacun suit la même convention de nommage du socle et utilise des templates Twig extensibles.

Le paragraphe Hero

Créez un type de paragraphe hero sur /admin/structure/paragraphs_type avec ces champs :

field_heading - texte brut
field_subheading - texte brut (optionnel)
field_image - référence media (image)
field_cta - lien

Puis ajoutez un template, paragraph--hero.html.twig :

{#
/**
 * @file
 * Default theme implementation for the Hero paragraph.
 */
#}
<section{{ attributes.addClass('paragraph', 'paragraph--hero') }}>
  <div class="paragraph--hero__media">
    {{ content.field_image }}
  </div>
  <div class="paragraph--hero__body">
    {% if content.field_heading|render|trim %}
      <h2 class="paragraph--hero__heading">{{ content.field_heading }}</h2>
    {% endif %}
    {{ content.field_subheading }}
    {{ content.field_cta }}
  </div>
</section>

La vérification |render|trim est une petite habitude importante : elle évite du markup wrapper vide quand un champ optionnel reste vide. Le même motif apparaît dans notre guide pour éditer et personnaliser un paragraphe Drupal rapidement.

Le paragraphe Texte + Image

Créez un type de paragraphe text_image avec :

field_heading - texte brut
field_body - texte formaté (long)
field_image - référence media (image)
field_image_position - liste (texte) : left, right

Lisez le champ position comme classe modificateur pour que le même composant puisse inverser son layout :

{% set position = content.field_image_position['#items'].value|default('left') %}
<section{{ attributes.addClass('paragraph', 'paragraph--text-image', 'paragraph--text-image--' ~ position) }}>
  <div class="paragraph--text-image__media">{{ content.field_image }}</div>
  <div class="paragraph--text-image__text">
    {% if content.field_heading|render|trim %}
      <h2>{{ content.field_heading }}</h2>
    {% endif %}
    {{ content.field_body }}
  </div>
</section>

.paragraph--text-image {
  display: grid;
  gap: 2rem;
  grid-template-columns: 1fr 1fr;
  align-items: center;
}
.paragraph--text-image--right .paragraph--text-image__media {
  order: 2;
}

Le paragraphe Feature Grid

Pour les éléments répétés, l’approche propre est les paragraphes imbriqués : un type feature_grid qui référence plusieurs paragraphes feature_item.

Créez d’abord un type feature_item avec field_icon (media), field_heading et field_text. Puis feature_grid avec :

field_heading - texte brut
field_items - entity reference revisions vers feature_item
field_columns - liste (integer) : 2, 3, 4

{% set columns = content.field_columns['#items'].value|default(3) %}
<section{{ attributes.addClass('paragraph', 'paragraph--feature-grid') }}>
  {% if content.field_heading|render|trim %}
    <h2 class="paragraph--feature-grid__heading">{{ content.field_heading }}</h2>
  {% endif %}
  <div class="paragraph--feature-grid__items" style="--columns: {{ columns }}">
    {{ content.field_items }}
  </div>
</section>

.paragraph--feature-grid__items {
  display: grid;
  gap: 1.5rem;
  grid-template-columns: repeat(var(--columns, 3), 1fr);
}

Imbriquer les paragraphes garde chaque feature item éditable indépendamment tandis que la grille ne contrôle que le layout - exactement la séparation de responsabilités qu’une bibliothèque maintenable nécessite.

Comment tester et valider l’expérience rédacteur ?

Avant de continuer, prouvez que le socle fonctionne du point de vue du rédacteur - pas seulement du vôtre.

Créez une page de test et ajoutez-y les trois types de paragraphes. Puis vérifiez trois choses :

Édition. Pouvez-vous ajouter, réordonner et supprimer des paragraphes facilement ? Le menu d’ajout est-il clair ?
Output. Le HTML rendu a-t-il une structure sensée et une hiérarchie de titres correcte ? Les champs optionnels vides ne produisent-ils pas de markup superflu ?
Responsivité. Le layout tient-il déjà quand vous réduisez le viewport, même avant le travail responsive dédié de la partie 2 ?

Si l’édition semble maladroite maintenant, ce sera pire avec dix types. Corriger le socle ici coûte bien moins cher que plus tard. La partie 2 de cette série ajoute contrôles d'espacement, variantes de couleur et layouts responsives - les fonctionnalités qui transforment une bibliothèque rigide en une que les rédacteurs font confiance sur de vraies pages. Pour un deep dive sur pourquoi l’espacement devient toujours un problème, voir espacement Drupal Paragraphs et lacunes de layout.

Vous voulez construire un site Drupal basé sur des composants avec Paragraphs ?

Ce Drupal Paragraphs tutorial s’appuie sur des patterns que nous utilisons sur des rebuilds corporate en production - planifier une petite bibliothèque universelle, imposer des conventions de nommage et prouver l’expérience rédacteur avant que la bibliothèque ne grandisse. Les trois types construits ici (Hero, Texte + Image, Feature Grid) sont le même socle que nous étendons avec variantes, espacement et UX admin dans la partie 2.

Vous construisez un site Drupal basé sur des composants et voulez des experts sur l’architecture ? Notre équipe conçoit et construit quotidiennement des systèmes Paragraphs adaptés aux rédacteurs - des templates Twig et types imbriqués aux contrôles d’espacement et à la maintenance long terme. Visitez notre agence Drupal pour voir comment nous pouvons vous aider.