Drupal : remplacer Colorbox par GLightbox

1 Introduction

Les plugins de lightbox sont un pilier des sites propulsés par Drupal depuis plus d’une décennie. Ils permettent aux éditeurs d’afficher des images, des vidéos et d’autres médias dans une superposition, sans quitter la page courante — un modèle auquel les visiteurs s’attendent sur les sites modernes riches en contenu multimédia.

Colorbox a historiquement été la solution de référence dans l’écosystème Drupal. Le module contribué colorbox s’intègre étroitement avec les formateurs de champs Image de Drupal, dispose d’une API mature et bénéficie d’une large familiarité au sein de la communauté. Toutefois, avec l’évolution du Web, Colorbox montre son âge : il dépend de jQuery, embarque une charge plus lourde et accuse un retard par rapport aux exigences contemporaines en matière d’accessibilité.

Voici GLightbox — une bibliothèque lightbox en JavaScript pur (sans aucune dépendance) offrant une interface soignée, une prise en charge robuste de l’accessibilité et une empreinte très légère. Le module Drupal correspondant s’intègre proprement aux mêmes champs Image et entités Media que Colorbox prenait auparavant en charge.

Cet article vous guide tout au long de la migration complète : de l’audit de votre configuration Colorbox actuelle à l’installation de GLightbox, en passant par le remappage des formateurs de champs, la suppression sécurisée de l’ancien module et l’ajustement fin de la nouvelle expérience pour votre thème.

2 Colorbox vs GLightbox : pourquoi migrer ?

2.1 Limitations de Colorbox

Colorbox a été créé à une autre époque du Web. Son architecture reflète des hypothèses qui ne sont plus valables dans le développement Drupal moderne :

• Dépendance à jQuery. Colorbox est un plugin jQuery — il ne peut pas fonctionner sans celui‑ci. Le cœur de Drupal réduit progressivement sa propre dépendance à jQuery, et de nombreux thèmes soucieux des performances chargent jQuery de manière paresseuse, voire pas du tout. Une dépendance stricte à jQuery va à l’encontre de cet objectif.
• Interface vieillissante et animations datées. Les styles par défaut de Colorbox paraissent obsolètes par rapport aux normes de design de 2024–2026. Une personnalisation CSS poussée est souvent nécessaire, ne serait‑ce que pour atteindre un rendu moderne de base.
• Lacunes en matière d’accessibilité. Bien que Colorbox ait reçu certains correctifs d’accessibilité au fil des ans, il n’a pas été conçu avec la conformité WCAG 2.1 AA comme objectif principal. Le piégeage du focus, les rôles ARIA et les annonces pour lecteurs d’écran peuvent nécessiter un travail supplémentaire conséquent.
• Rythme de maintenance. La bibliothèque Colorbox jQuery en amont est mise à jour peu fréquemment. Pour un projet Drupal sur le long terme, s’appuyer sur une dépendance maintenue lentement introduit un risque.

2.2 Avantages de GLightbox

GLightbox répond directement à chacun des points de douleur ci‑dessus :

• Aucune dépendance. JavaScript ES6+ pur ; pas de jQuery requis.
• UX moderne. Transitions CSS fluides, gestes tactiles, navigation clavier et thème par défaut épuré s’intégrant bien aux designs contemporains.
• Accessibilité de premier ordre. Le focus est confiné à l’intérieur de la lightbox, la navigation au clavier avec les flèches fonctionne par défaut et les rôles ARIA appropriés role="dialog" sont appliqués automatiquement.
• Léger. Le bundle minifié et compressé (gzip) pèse moins de 15 Ko — environ trois fois plus léger qu’une configuration Colorbox typique.
• Regroupement en galerie. Support natif des galeries groupées via l’attribut data-gallery, sans plugin additionnel.
• Développement actif. Le projet GLightbox sur GitHub bénéficie de publications régulières et de corrections de bugs.

3 Vue d’ensemble de l’écosystème Drupal

Le cœur de Drupal suit depuis plusieurs années une trajectoire visant à réduire son empreinte jQuery, en favorisant le JavaScript natif et les API modernes des navigateurs. Cette évolution se reflète dans la dépréciation de nombreux comportements basés sur jQuery dans Drupal 10+ et dans l’incitation faite aux thèmes d’adopter des stratégies JavaScript plus légères.

Côté contribution, Colorbox comme GLightbox disposent de modules Drupal dédiés sur Drupal.org :

• colorbox — le choix classique, avec une intégration approfondie des formateurs de champs Image, de Views et du système Media. Il reste largement installé, mais reçoit moins de mises à jour.
• glightbox — un module contribué plus récent encapsulant la bibliothèque JavaScript GLightbox. Il fournit des formateurs de champs Image et Media, une prise en charge de Views, ainsi qu’un formulaire de paramètres pour les options GLightbox courantes.

4 Préparer la migration

4.1 Auditer l’utilisation actuelle de Colorbox

Avant de modifier la moindre configuration, établissez une vue complète des endroits et des modalités d’utilisation de Colorbox sur votre site :

1. Champs image. Rendez‑vous dans Structure → Types de contenu → [Type] → Gérer l’affichage pour chaque type de contenu et vérifiez si un champ image utilise le formateur Colorbox. Notez les styles d’image et les paramètres de légende.
2. Entités Media. Vérifiez les modes d’affichage des types de médias dans Structure → Types de médias. Répétez l’opération pour chaque type de média impliquant des images ou des vidéos.
3. Views. Recherchez les Views qui affichent des champs image et vérifiez le formateur de champ utilisé. Colorbox peut également être appliqué via le plugin de format « Colorbox » de Views.
4. Code personnalisé. Recherchez dans vos modules et thèmes personnalisés les références à colorbox, .colorbox, Drupal.behaviors.colorbox et à la clé de bibliothèque colorbox/colorbox.

# Recherche rapide dans l’ensemble du code (exécuter à la racine Drupal)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Notez soigneusement chaque occurrence trouvée. Vous y reviendrez une par une lors de la phase de remplacement.

4.2 Sauvegardes et considérations d’environnement

• Exporter la configuration active : drush config:export
• Committer l’export dans le contrôle de version avant de commencer
• Désactiver l’agrégation CSS/JS pendant la migration (Administration → Performance)
• Effectuer une sauvegarde de la base de données : drush sql:dump > pre-migration.sql
• S’assurer que le pipeline de déploiement peut propager les changements de configuration vers la préproduction et la production

5 Installation et activation de GLightbox dans Drupal

5.1 Installer la bibliothèque JavaScript GLightbox

Le module Drupal GLightbox dépend de la bibliothèque amont GLightbox JS. Deux méthodes prises en charge permettent de la fournir.

Option A — Composer + Asset Packagist (recommandé)

# Ajouter Asset Packagist comme dépôt (une seule fois par projet)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Installer la bibliothèque
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Ajoutez ou vérifiez le chemin d’installation pour npm-asset dans la section extra.installer-paths de votre composer.json :

"extra": {
  "installer-types": ["npm-asset", "bower-asset"],
  "installer-paths": {
    "web/libraries/{$name}": [
      "type:drupal-library",
      "type:npm-asset",
      "type:bower-asset"
    ]
  }
}

Après l’exécution de composer install, la bibliothèque sera installée dans web/libraries/glightbox/.

Option B — Installation manuelle

Téléchargez la dernière version depuis la page des releases GitHub de GLightbox et placez les fichiers afin que les chemins suivants existent :

web/libraries/glightbox/dist/js/glightbox.min.js
web/libraries/glightbox/dist/css/glightbox.min.css

5.2 Installer et activer le module Drupal GLightbox

# Télécharger le module
composer require drupal/glightbox

# L’activer
drush en glightbox -y

# Vider les caches
drush cr

Accédez à Administration → Configuration → Médias → GLightbox pour confirmer que la bibliothèque est détectée et explorer les options de configuration globales.

6 Remplacer les fonctionnalités de Colorbox

6.1 Champs image

Il s’agit du cas d’usage le plus courant de Colorbox : un champ image sur un type de contenu affichant une vignette qui ouvre l’image en taille réelle dans une lightbox.

1. Accédez à Structure → Types de contenu → [Votre type] → Gérer l’affichage.
2. Repérez le champ image. Dans le menu déroulant Format, remplacez Colorbox par GLightbox.
3. Cliquez sur l’icône d’engrenage (⚙) pour configurer le formateur. Définissez le Style d’image (vignette affichée sur la page) et le Style d’image liée (image chargée dans la lightbox). Activez les légendes si nécessaire.
4. Enregistrez la configuration d’affichage et videz les caches : drush cr.

Vous pouvez également effectuer cette configuration via une exportation YAML. Exemple de configuration de formateur de champ dans un fichier d’affichage de type de contenu :

# core.entity_view_display.node.article.default.yml (extrait)
dependencies:
  module:
    - glightbox
    - image
content:
  field_image:
    type: glightbox
    label: hidden
    settings:
      image_style: medium
      image_link: ''
      glightbox_image_style: large
      glightbox_gallery: ''
      glightbox_caption: title
      glightbox_caption_custom: ''
    third_party_settings: {  }

6.2 Médias et galeries

Pour les sites utilisant le système Media de Drupal, les étapes de migration sont similaires, mais s’appliquent aux modes d’affichage des types de médias.

• Accédez à Structure → Types de médias → [Type] → Gérer l’affichage.
• Remplacez le formateur du champ source de l’image de Colorbox à GLightbox.
• Pour le regroupement en galerie, configurez le champ ID de galerie dans les paramètres du formateur GLightbox. Tous les éléments partageant le même ID de galerie pourront être parcourus comme un groupe dans la lightbox. Cela correspond directement à l’attribut natif data-gallery de GLightbox.

Le mappage des légendes est simple : GLightbox lit l’attribut data-description. Le module Drupal permet de le lier au champ title ou alt de l’image, ou à une valeur de champ personnalisée.

6.3 Intégration avec Views

Si des Views affichent des images avec un formatage Colorbox, mettez à jour chaque View comme suit :

1. Ouvrez la View dans Structure → Views → [Nom de la vue] → Modifier.
2. Dans la section Champs, cliquez sur le champ image. Dans le menu déroulant Formateur, remplacez Colorbox par GLightbox.
3. Si l’intégration Colorbox était gérée au niveau du Format (par exemple via un plugin de format « Colorbox »), remplacez‑le par un format standard tel que Liste non formatée ou Grille, puis appliquez le formateur GLightbox au niveau du champ.
4. Enregistrez et videz les caches.

7 Supprimer Colorbox en toute sécurité

Une fois tous les formateurs et le code personnalisé migrés, vous pouvez supprimer Colorbox en toute sécurité. Suivez cet ordre précis afin d’éviter les erreurs de dépendance :

1. Désactiver le module Colorbox. La désactivation avant la désinstallation permet à Drupal d’exécuter son nettoyage via hook_uninstall().

   drush pm:uninstall colorbox -y

2. Supprimer la dépendance de composer.json.

   composer remove drupal/colorbox

3. Supprimer la bibliothèque JavaScript Colorbox du répertoire web/libraries/colorbox/ si elle a été installée manuellement.
4. Nettoyer le code personnalisé. Recherchez et supprimez toute référence restante aux classes CSS Colorbox (.colorbox, .colorbox-load), aux comportements JavaScript (Drupal.behaviors.colorbox) ou aux attachements de bibliothèque (colorbox/colorbox).

5. Vider tous les caches et exporter la configuration.

   drush cr
   drush config:export

8 Personnalisation et améliorations

8.1 Options de configuration de GLightbox

La page de paramètres globaux de GLightbox (Administration → Configuration → Médias → GLightbox) expose les options les plus couramment utilisées. Celles‑ci correspondent directement à l’API JavaScript de GLightbox :

8.2 Thématisation et styles

GLightbox est livré avec une feuille de style par défaut (glightbox.min.css) proposant un design sombre et épuré. Vous pouvez la surcharger dans votre thème sans modifier le fichier de la bibliothèque :

/* mytheme/css/glightbox-overrides.css */

/* Modifier l’arrière-plan de la superposition */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* Styliser la zone de légende */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* Agrandir les flèches de navigation */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* Variante en mode clair */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

Attachez la feuille de style de surcharge dans le fichier .libraries.yml de votre thème :

# mytheme.libraries.yml
glightbox-overrides:
  version: VERSION
  css:
    theme:
      css/glightbox-overrides.css: {}
  dependencies:
    - glightbox/glightbox

Puis attachez‑la globalement dans mytheme.info.yml :

# mytheme.info.yml (extrait)
libraries:
  - mytheme/glightbox-overrides

8.3 Cas d’utilisation avancés

Attachement programmatique via #attached

Vous pouvez attacher la bibliothèque GLightbox à n’importe quel tableau de rendu dans un module personnalisé ou un hook de pré‑traitement :

// Dans une fonction de preprocess ou un build() de bloc personnalisé
$build['#attached']['library'][] = 'glightbox/glightbox';

// Transmettre des surcharges de configuration aux paramètres JS
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Déclencheurs personnalisés dans les templates Twig

Pour créer manuellement un déclencheur GLightbox dans un template Twig, ajoutez les attributs appropriés. GLightbox détecte tout élément portant class="glightbox" (ou le selector configuré) :

{# Ouvrir une image unique #}
<a href="{{ file_url(node.field_hero_image.entity.uri.value) }}"
   class="glightbox"
   data-title="{{ node.label }}"
   data-description="{{ node.field_caption.value }}">
  {{ content.field_hero_image }}
</a>

{# Groupe de galerie — tous les éléments partageant le même data-gallery s’ouvrent ensemble #}
{% for item in node.field_gallery %}
  <a href="{{ file_url(item.entity.uri.value) }}"
     class="glightbox"
     data-gallery="gallery-{{ node.id }}"
     data-description="{{ item.alt }}">
    <img src="{{ file_url(item.entity.uri.value) | image_style('thumbnail') }}"
         alt="{{ item.alt }}" />
  </a>
{% endfor %}

Comportement Drupal pour une initialisation personnalisée

Si vous devez initialiser GLightbox avec des options non exposées par l’interface d’administration du module, utilisez un comportement Drupal personnalisé :

// mytheme/js/glightbox-init.js
(function (Drupal, drupalSettings) {
  'use strict';

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // Initialisation unique par contexte
      const elements = context.querySelectorAll('.glightbox-custom:not(.glightbox-processed)');
      if (!elements.length) return;

      elements.forEach(el => el.classList.add('glightbox-processed'));

      const lightbox = GLightbox({
        selector: '.glightbox-custom',
        touchNavigation: true,
        loop: true,
        animation: 'fade',
        autoplayVideos: settings.glightbox?.autoplayVideos ?? true,
      });
    },
  };

}(Drupal, drupalSettings));

9 Tests et assurance qualité

Une fois la migration terminée, parcourez la liste de vérification suivante avant tout déploiement en production :

Tests fonctionnels

• Les images s’ouvrent dans la lightbox au clic, sur tous les types de contenu concernés
• La navigation dans les galeries (flèches précédent/suivant, flèches du clavier) fonctionne correctement
• Les légendes s’affichent et correspondent à la valeur de champ attendue
• Les vidéos (YouTube, Vimeo, locales) se lancent automatiquement et se ferment correctement
• La fermeture de la lightbox (bouton ✕, touche Échap, clic extérieur) restaure correctement le focus

Tests multi‑navigateurs

• Chrome/Edge (Chromium), Firefox, Safari (macOS et iOS)
• Vérifier que les transitions CSS s’affichent correctement dans tous les navigateurs testés

Tests mobiles et tactiles

• Balayage gauche/droite pour naviguer entre les éléments de la galerie
• Zoom par pincement sur les images (si activé)
• La superposition couvre correctement l’écran sur les petits formats

Vérifications d’accessibilité

• La touche Tab fait correctement circuler le focus entre les contrôles de la lightbox (fermer, précédent, suivant)
• Le focus revient à l’élément déclencheur après la fermeture
• Le lecteur d’écran annonce correctement la boîte de dialogue et son contenu (test avec NVDA ou VoiceOver)
• Exécuter un audit d’accessibilité avec axe DevTools ou Lighthouse — objectif : zéro erreur critique

Performances

• Réactiver l’agrégation CSS/JS et vérifier que GLightbox s’initialise toujours correctement
• Exécuter un audit de performance Lighthouse et comparer avec la référence Colorbox
• Vérifier l’absence d’erreurs JavaScript dans la console sur toutes les pages testées

10 Problèmes courants et dépannage

Les images ne s’ouvrent pas dans la lightbox

Symptôme : Un clic sur l’image redirige vers l’URL liée au lieu d’ouvrir GLightbox.

• Vérifiez que la bibliothèque GLightbox est bien chargée : ouvrez les DevTools du navigateur → onglet Réseau, filtrez sur glightbox. Si elle est absente, assurez‑vous que les fichiers existent dans web/libraries/glightbox/dist/.
• Vérifiez que l’agrégation CSS/JS fonctionne correctement ; essayez de la désactiver temporairement pour isoler les problèmes liés à l’agrégation.
• Inspectez le HTML rendu pour confirmer que l’élément déclencheur possède bien l’attribut class="glightbox" (ou le sélecteur personnalisé configuré).

Légendes manquantes ou galeries défectueuses

Symptôme : Les légendes sont vides ou la navigation de galerie saute des éléments.

• Inspectez les balises <a> rendues : vérifiez que data-description est renseigné et que les valeurs data-gallery correspondent entre les éléments groupés.
• Vérifiez que le paramètre de formateur Source de légende pointe vers un champ non vide.
• Pour le regroupement en galerie, confirmez que l’ID de galerie est cohérent ; les ID générés par token peuvent être vides si le module Token n’est pas installé.

Conflits avec d’autres bibliothèques JavaScript

Symptôme : GLightbox s’initialise partiellement ou génère des erreurs dans la console.

• Vérifiez l’absence de chargements dupliqués de la bibliothèque GLightbox (module + attachement manuel dans le thème).
• Assurez‑vous qu’aucune autre bibliothèque ne surcharge window.GLightbox.
• Si votre thème utilise un bundler JavaScript, vérifiez que GLightbox n’est pas embarqué séparément en plus de l’attachement via le système d’assets de Drupal.

Problèmes de cache et d’agrégation

Symptôme : GLightbox fonctionne en développement mais échoue en production.

• Exécutez drush cr en production après avoir déployé les changements de configuration.
• Vérifiez que web/libraries/glightbox/ est bien présent dans le dépôt ou déployé correctement — ce répertoire est parfois exclu par des règles .gitignore. Envisagez l’utilisation de composer install --no-dev dans votre pipeline CI/CD.
• Si l’agrégation CSS compresse la feuille GLightbox d’une manière qui casse la spécificité des sélecteurs, assurez‑vous que votre fichier de surcharge est chargé plus tard dans l’ordre des assets.

# Vider tous les caches en production (si Drush est disponible)
drush @prod cr

# Vérifier la présence du fichier de bibliothèque
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Conclusion

Migrer de Colorbox vers GLightbox constitue une étape significative de modernisation frontend pour tout projet Drupal. Les bénéfices sont concrets :

• Éliminer la dépendance à jQuery dans votre chaîne lightbox
• Offrir une expérience plus rapide et plus légère aux visiteurs
• Bénéficier d’une conformité accessibilité prête à l’emploi sans correctifs personnalisés
• S’aligner sur l’orientation du cœur de Drupal vers le JavaScript natif
• Réduire la charge de maintenance à long terme grâce à une bibliothèque activement développée

La migration elle‑même présente peu de risques lorsqu’elle est menée méthodiquement : audit préalable, migration progressive des formateurs, nettoyage du code hérité et tests approfondis avant déploiement. Le module Drupal glightbox rend la majeure partie de ce travail déclarative, via la configuration plutôt que du code personnalisé.

Pour les sites engagés dans une modernisation frontend plus large — architecture découplée ou headless, adoption d’un thème moderne (Olivero, Gin ou un design system personnalisé), ou réduction du poids JavaScript — le remplacement de Colorbox par GLightbox constitue un excellent point de départ, à faible risque et à impact visible.