Drupal: Colorbox durch GLightbox ersetzen

1 Einführung

Lightbox-Plugins sind seit über einem Jahrzehnt ein fester Bestandteil von Drupal-basierten Websites. Sie ermöglichen es Redakteurinnen und Redakteuren, Bilder, Videos und andere Medien in einer Overlay-Darstellung anzuzeigen, ohne die aktuelle Seite zu verlassen – ein Muster, das Besucherinnen und Besucher auf modernen, medienreichen Websites erwarten.

Colorbox war historisch die bevorzugte Lösung im Drupal-Ökosystem. Das beitragende Modul colorbox ist eng mit Drupals Bildfeld-Formatierern gekoppelt, verfügt über eine ausgereifte API und ist in der Community weit verbreitet. Mit der Weiterentwicklung des Webs zeigt Colorbox jedoch sein Alter: Es ist von jQuery abhängig, bringt ein größeres Payload mit sich und hinkt modernen Accessibility-Anforderungen hinterher.

Hier kommt GLightbox ins Spiel – eine reine Vanilla-JavaScript-Lightbox-Bibliothek (keine Abhängigkeiten) mit einer ausgereiften Benutzeroberfläche, robuster Barrierefreiheits-Unterstützung und einem sehr schlanken Footprint. Das dazugehörige Drupal-Modul integriert sich nahtlos in dieselben Bildfelder und Media-Entities, die zuvor von Colorbox bedient wurden.

Dieser Artikel führt Sie durch die vollständige Migration: von der Analyse Ihrer bestehenden Colorbox-Konfiguration über die Installation von GLightbox, das Neu-Zuordnen von Feld-Formatierern, das sichere Entfernen des alten Moduls bis hin zur Feinabstimmung der neuen Lösung für Ihr Theme.

2 Colorbox vs. GLightbox: Warum migrieren?

2.1 Einschränkungen von Colorbox

Colorbox wurde in einer anderen Phase der Webentwicklung erstellt. Seine Architektur basiert auf Annahmen, die in der modernen Drupal-Entwicklung nicht mehr zutreffen:

• jQuery-Abhängigkeit. Colorbox ist ein jQuery-Plugin – ohne jQuery nicht lauffähig. Drupal Core reduziert seit Jahren schrittweise seine jQuery-Nutzung, und viele performanceorientierte Themes laden jQuery nur verzögert oder gar nicht. Eine harte jQuery-Abhängigkeit wirkt diesem Ziel entgegen.
• Veraltete UI und Animationen. Die Standard-Styles von Colorbox wirken im Vergleich zu den Designstandards von 2024–2026 überholt. Umfangreiche CSS-Anpassungen sind oft nötig, um überhaupt ein modernes Grundniveau zu erreichen.
• Barrierefreiheitsdefizite. Obwohl Colorbox im Laufe der Jahre einige Accessibility-Patches erhalten hat, wurde es nicht mit WCAG 2.1 AA als primärem Ziel entwickelt. Fokus-Trapping, ARIA-Rollen und Screenreader-Ankündigungen erfordern häufig erhebliche Zusatzarbeit.
• Geringe Wartungsdynamik. Die zugrunde liegende jQuery-Colorbox-Bibliothek wird nur selten aktualisiert. Für langlebige Drupal-Projekte bedeutet eine langsam gepflegte Abhängigkeit ein erhöhtes Risiko.

2.2 Vorteile von GLightbox

GLightbox adressiert jeden der oben genannten Schwachpunkte gezielt:

• Keine Abhängigkeiten. Reines ES6+-JavaScript; kein jQuery erforderlich.
• Moderne UX. Weiche CSS-Transitions, Swipe-Gesten, Tastaturnavigation und ein schlankes Standard-Theme, das sich gut in zeitgemäße Designs integriert.
• Erstklassige Barrierefreiheit. Der Fokus wird innerhalb der Lightbox gehalten, Pfeiltasten-Navigation funktioniert sofort, und korrekte ARIA-role="dialog"-Semantik wird automatisch angewendet.
• Sehr leichtgewichtig. Das minimierte und komprimierte Bundle liegt unter 15 KB – etwa dreimal kleiner als ein typisches Colorbox-Setup.
• Galerie-Gruppierung. Native Unterstützung für gruppierte Galerien über das data-gallery-Attribut – ganz ohne zusätzliche Plugins.
• Aktive Weiterentwicklung. Das GLightbox-Projekt auf GitHub erhält regelmäßig Releases und Bugfixes.

3 Überblick über das Drupal-Ökosystem

Drupal Core befindet sich seit mehreren Jahren auf dem Weg, seinen jQuery-Footprint zu reduzieren und verstärkt auf Vanilla-JavaScript sowie moderne Browser-APIs zu setzen. Dies spiegelt sich in der Deprecation vieler jQuery-basierter Verhaltensweisen in Drupal 10+ sowie im Bestreben wider, Themes zu schlankeren JavaScript-Strategien zu bewegen.

Auf der Contrib-Seite gibt es sowohl für Colorbox als auch für GLightbox dedizierte Drupal-Module auf Drupal.org:

• colorbox — die klassische Wahl mit tiefer Integration in Bildfeld-Formatierer, Views und das Media-System. Noch weit verbreitet installiert, erhält jedoch weniger Updates.
• glightbox — ein neueres Contrib-Modul, das die GLightbox-JavaScript-Bibliothek kapselt. Bietet Bild- und Media-Feld-Formatierer, Views-Unterstützung sowie eine Einstellungsseite für gängige GLightbox-Optionen.

4 Vorbereitung der Migration

4.1 Bestehende Colorbox-Nutzung analysieren

Bevor Sie Änderungen an der Konfiguration vornehmen, verschaffen Sie sich einen vollständigen Überblick darüber, wo und wie Colorbox auf Ihrer Website eingesetzt wird:

1. Bildfelder. Öffnen Sie Struktur → Inhaltstypen → [Typ] → Anzeige verwalten für jeden Inhaltstyp und prüfen Sie, ob ein Bildfeld den Colorbox-Formatierer verwendet. Notieren Sie Bildstile und Caption-Einstellungen.
2. Media-Entitäten. Prüfen Sie die Anzeige-Modi der Medientypen unter Struktur → Medientypen. Wiederholen Sie dies für alle Medientypen mit Bildern oder Videos.
3. Views. Suchen Sie nach Views mit Bildfeldern und prüfen Sie, welcher Feld-Formatierer verwendet wird. Colorbox kann auch über das Views-Format-Plugin „Colorbox“ eingebunden sein.
4. Eigenentwickelter Code. Durchsuchen Sie eigene Module und Themes nach Referenzen auf colorbox, .colorbox, Drupal.behaviors.colorbox sowie nach dem Library-Key colorbox/colorbox.

# Schnelle Suche im Codebestand (vom Drupal-Root ausführen)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Notieren Sie jede gefundene Stelle. Sie werden jede davon in der Ersetzungsphase erneut prüfen.

4.2 Backup- und Umgebungsüberlegungen

• Aktive Konfiguration exportieren: drush config:export
• Export vor Beginn in der Versionskontrolle committen
• CSS/JS-Aggregation während der Migration deaktivieren (Admin → Performance)
• Datenbank-Dump erstellen: drush sql:dump > pre-migration.sql
• Sicherstellen, dass die Deployment-Pipeline Konfigurationsänderungen nach Staging/Produktion ausrollen kann

5 Installation und Aktivierung von GLightbox in Drupal

5.1 Installation der GLightbox-JavaScript-Bibliothek

Das Drupal-GLightbox-Modul basiert auf der Upstream‑GLightbox-JavaScript-Bibliothek. Es gibt zwei unterstützte Möglichkeiten, diese bereitzustellen.

Option A — Composer + Asset Packagist (Empfohlen)

# Asset Packagist als Repository hinzufügen (einmal pro Projekt)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Library installieren
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Ergänzen oder prüfen Sie den Installer-Pfad für npm-asset im Abschnitt extra.installer-paths Ihrer composer.json:

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

Nach dem Ausführen von composer install befindet sich die Bibliothek unter web/libraries/glightbox/.

Option B — Manuelle Ablage

Laden Sie das neueste Release von der GLightbox‑GitHub‑Releases-Seite herunter und platzieren Sie den Inhalt so, dass folgende Pfade existieren:

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

5.2 Installation und Aktivierung des GLightbox-Drupal-Moduls

# Modul herunterladen
composer require drupal/glightbox

# Modul aktivieren
drush en glightbox -y

# Caches leeren
drush cr

Navigieren Sie zu Admin → Konfiguration → Medien → GLightbox, um zu prüfen, ob die Library erkannt wird, und um die globalen Konfigurationsoptionen zu erkunden.

6 Ersetzen der Colorbox-Funktionalität

6.1 Bildfelder

Dies ist der häufigste Anwendungsfall von Colorbox: Ein Bildfeld in einem Inhaltstyp zeigt eine Vorschau, die beim Anklicken das Bild in voller Größe in einer Lightbox öffnet.

1. Öffnen Sie Struktur → Inhaltstypen → [Ihr Typ] → Anzeige verwalten.
2. Suchen Sie das Bildfeld. Ändern Sie im Dropdown Format den Formatierer von Colorbox zu GLightbox.
3. Klicken Sie auf das Einstellungs-Zahnrad (⚙), um den Formatierer zu konfigurieren. Legen Sie den Bildstil (Vorschaubild auf der Seite) sowie den Verlinkten Bildstil (Bild innerhalb der Lightbox) fest. Aktivieren Sie bei Bedarf Beschriftungen.
4. Speichern Sie die Anzeigeeinstellungen und leeren Sie die Caches: drush cr.

Alternativ können Sie diese Konfiguration exportieren und per YAML anwenden. Ein Beispiel für eine Feld-Formatierer-Konfiguration in der Anzeige eines Inhaltstyps:

# core.entity_view_display.node.article.default.yml (Auszug)
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 Media und Galerien

Für Websites, die das Drupal‑Media‑System verwenden, sind die Migrationsschritte ähnlich, werden jedoch auf die Anzeige-Modi der Medientypen angewendet.

• Öffnen Sie Struktur → Medientypen → [Typ] → Anzeige verwalten.
• Wechseln Sie beim Bildquellfeld den Formatierer von Colorbox zu GLightbox.
• Für die Galerie‑Gruppierung konfigurieren Sie im GLightbox‑Formatierer das Feld Galerie‑ID. Alle Elemente mit derselben Galerie‑ID können innerhalb der Lightbox gemeinsam navigiert werden. Dies entspricht direkt dem nativen data-gallery-Attribut von GLightbox.

Die Zuordnung von Beschriftungen ist unkompliziert: GLightbox liest das data-description-Attribut. Das Drupal‑Modul erlaubt die Zuordnung zum title- oder alt-Attribut des Bildes oder zu einem benutzerdefinierten Feldwert.

6.3 Integration mit Views

Wenn Views Bilder mit Colorbox darstellen, aktualisieren Sie jede View wie folgt:

1. Öffnen Sie die View unter Struktur → Views → [Name der View] → Bearbeiten.
2. Klicken Sie unter Felder auf das Bildfeld. Wechseln Sie im Dropdown Formatierer von Colorbox zu GLightbox.
3. Wurde Colorbox auf Format-Ebene eingebunden (z. B. über ein „Colorbox“-Format‑Plugin), wechseln Sie zu einem Standardformat wie Unformatierte Liste oder Raster und wenden Sie den GLightbox‑Formatierer stattdessen auf Feld‑Ebene an.
4. Speichern Sie die Änderungen und leeren Sie die Caches.

7 Colorbox sicher entfernen

Sobald alle Formatierer und benutzerdefinierten Code-Stellen migriert wurden, können Sie Colorbox gefahrlos entfernen. Halten Sie die folgende Reihenfolge ein, um Abhängigkeitsfehler zu vermeiden:

1. Colorbox-Modul deaktivieren. Das Deaktivieren vor der Deinstallation ermöglicht Drupal, die Aufräumlogik aus hook_uninstall() auszuführen.

   drush pm:uninstall colorbox -y

2. Aus der composer.json entfernen.

   composer remove drupal/colorbox

3. Colorbox-JS-Library entfernen aus web/libraries/colorbox/, sofern sie manuell abgelegt wurde.
4. Benutzerdefinierten Code bereinigen. Suchen und entfernen Sie verbliebene Referenzen auf Colorbox‑CSS‑Klassen (.colorbox, .colorbox-load), JavaScript‑Behaviors (Drupal.behaviors.colorbox) oder Library‑Anhänge (colorbox/colorbox).

5. Alle Caches leeren und Konfiguration exportieren.

   drush cr
   drush config:export

8 Anpassungen und Erweiterungen

8.1 GLightbox-Konfigurationsoptionen

Die globale GLightbox-Einstellungsseite (Admin → Konfiguration → Medien → GLightbox) stellt die am häufigsten benötigten Optionen bereit. Diese entsprechen direkt der JavaScript-API von GLightbox:

8.2 Theming und Styling

GLightbox wird mit einem Standard-Stylesheet (glightbox.min.css) ausgeliefert, das ein klares Design mit dunklem Overlay bereitstellt. Überschreiben Sie dieses in Ihrem Theme, ohne die Library-Datei selbst zu verändern:

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

/* Hintergrund des Overlays anpassen */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* Caption-Bereich gestalten */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* Navigationspfeile vergrößern */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* Variante für hellen Modus */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

Binden Sie das Override-Stylesheet in der .libraries.yml Ihres Themes ein:

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

Anschließend binden Sie es global in mytheme.info.yml ein:

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

8.3 Fortgeschrittene Anwendungsfälle

Programmatisches Einbinden über #attached

Sie können die GLightbox-Library an jedes Render-Array in einem eigenen Modul oder Preprocess-Hook anhängen:

// In einer Preprocess-Funktion oder in build() eines Custom-Blocks
$build['#attached']['library'][] = 'glightbox/glightbox';

// Konfigurationsüberschreibungen an JS-Settings übergeben
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Eigene Trigger in Twig-Templates

Um manuell einen GLightbox-Trigger in einem Twig-Template zu erstellen, fügen Sie die korrekten Attribute hinzu. GLightbox erkennt jedes Element mit class="glightbox" (oder dem konfigurierten selector):

{# Einzelnes Bild öffnen #}
<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>

{# Galerie — alle Elemente mit gleicher data-gallery-ID öffnen gemeinsam #}
{% 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 %}

Drupal-Behavior für benutzerdefinierte Initialisierung

Wenn Sie GLightbox mit Optionen initialisieren müssen, die nicht über die Admin-Oberfläche des Moduls verfügbar sind, verwenden Sie ein eigenes Drupal-Behavior:

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

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // Nur einmal pro Context initialisieren
      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 Testing und Qualitätssicherung

Nach Abschluss der Migration sollten Sie vor dem Deployment in die Produktion die folgende QA‑Checkliste vollständig durchgehen:

Funktionale Tests

• Bilder öffnen sich beim Klick in der Lightbox für alle betroffenen Inhaltstypen
• Galerie-Navigation (Zurück-/Weiter‑Pfeile, Pfeiltasten auf der Tastatur) funktioniert korrekt
• Beschriftungen werden angezeigt und entsprechen dem erwarteten Feldwert
• Video-Elemente (YouTube, Vimeo, lokal) starten automatisch und schließen korrekt
• Das Schließen der Lightbox (✕‑Button, Escape‑Taste, Klick außerhalb) stellt den Fokus wieder her

Cross-Browser-Tests

• Chrome/Edge (Chromium), Firefox, Safari (macOS und iOS)
• Verifizieren Sie, dass CSS-Transitions in allen getesteten Browsern korrekt dargestellt werden

Mobile- und Touch-Tests

• Wischen nach links/rechts navigiert korrekt durch Galerien
• Pinch‑to‑Zoom auf Bildern (falls aktiviert)
• Overlay deckt den Viewport auf kleinen Bildschirmen korrekt ab

Barrierefreiheits‑Checks

• Tab‑Taste durchläuft alle Lightbox‑Steuerelemente (Schließen, Zurück, Weiter)
• Nach dem Schließen kehrt der Fokus zum auslösenden Element zurück
• Screenreader kündigt den Dialog und dessen Inhalt korrekt an (z. B. mit NVDA oder VoiceOver testen)
• axe DevTools oder Lighthouse‑Accessibility‑Audit ausführen — Ziel: keine kritischen Fehler

Performance

• CSS/JS‑Aggregation wieder aktivieren und sicherstellen, dass GLightbox weiterhin initialisiert wird
• Lighthouse‑Performance‑Audit ausführen und mit der Colorbox‑Baseline vergleichen
• Sicherstellen, dass keine JavaScript‑Konsolenfehler auf getesteten Seiten auftreten

10 Häufige Probleme und Fehlerbehebung

Bilder öffnen sich nicht in der Lightbox

Symptom: Beim Anklicken des Bildes wird zur verlinkten URL navigiert, anstatt GLightbox zu öffnen.

• Prüfen Sie, ob die GLightbox-Library geladen wird: Öffnen Sie die Browser‑DevTools → Registerkarte Network und filtern Sie nach glightbox. Fehlt sie, stellen Sie sicher, dass sich die Library-Dateien unter web/libraries/glightbox/dist/ befinden.
• Stellen Sie sicher, dass die CSS/JS‑Aggregation korrekt funktioniert; deaktivieren Sie sie testweise, um aggregationsbedingte Probleme einzugrenzen.
• Prüfen Sie das gerenderte HTML und stellen Sie sicher, dass das auslösende Element das Attribut class="glightbox" besitzt (oder den von Ihnen konfigurierten Custom‑Selector).

Fehlende Beschriftungen oder defekte Galerien

Symptom: Beschriftungen sind leer oder die Galerie‑Navigation überspringt Elemente.

• Untersuchen Sie die gerenderten <a>-Tags: Vergewissern Sie sich, dass data-description gesetzt ist und dass die data-gallery-Werte bei gruppierten Elementen übereinstimmen.
• Prüfen Sie, ob die Einstellung Quelle für Beschriftung im Feld‑Formatierer auf ein nicht leeres Feld verweist.
• Bei Galerie‑Gruppierungen sicherstellen, dass die Galerie‑ID konsistent ist; tokenbasierte IDs können leere Werte ergeben, wenn das Token‑Modul nicht installiert ist.

Konflikte mit anderen JavaScript‑Libraries

Symptom: GLightbox initialisiert nur teilweise oder wirft Fehler in der Konsole.

• Prüfen Sie, ob die GLightbox-Library doppelt geladen wird (z. B. gleichzeitig über Modul und manuelles Theme‑Attachment).
• Stellen Sie sicher, dass keine andere Library window.GLightbox überschreibt.
• Wenn Ihr Theme einen JavaScript‑Bundler verwendet, stellen Sie sicher, dass GLightbox nicht zusätzlich gebündelt wird, während es bereits über Drupals Asset‑System eingebunden ist.

Cache‑ und Aggregationsprobleme

Symptom: GLightbox funktioniert in der Entwicklungsumgebung, aber nicht in der Produktion.

• Führen Sie nach dem Deployment von Konfigurationsänderungen drush cr auf der Produktionsumgebung aus.
• Verifizieren Sie, dass web/libraries/glightbox/ korrekt eingecheckt oder bereitgestellt wurde — dieser Pfad wird manchmal von .gitignore-Regeln ausgeschlossen, die das libraries/-Verzeichnis betreffen. Erwägen Sie den Einsatz von composer install --no-dev in Ihrer CI/CD‑Pipeline, um sicherzustellen, dass die Library korrekt platziert wird.
• Wenn die CSS‑Aggregation das GLightbox‑Stylesheet so komprimiert, dass die Selektor‑Spezifität leidet, binden Sie Ihre Override‑Datei später in der Asset‑Reihenfolge ein.

# Alle Caches auf Produktion leeren (sofern Drush verfügbar ist)
drush @prod cr

# Prüfen, ob die Library-Datei vorhanden ist
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Fazit

Die Migration von Colorbox zu GLightbox ist ein sinnvoller Schritt zur Frontend‑Modernisierung für jedes Drupal‑Projekt. Die Vorteile sind klar und messbar:

• Eliminierung der jQuery‑Laufzeitabhängigkeit im Lightbox‑Pfad
• Schnellere und schlankere Benutzererfahrung für Ihre Besucherinnen und Besucher
• Barrierefreiheits‑Compliance ohne zusätzliche individuelle Patches
• Ausrichtung an der strategischen Entwicklung von Drupal Core hin zu Vanilla‑JavaScript
• Reduzierter langfristiger Wartungsaufwand durch eine aktiv entwickelte Library

Die Migration selbst ist risikoarm, wenn sie strukturiert durchgeführt wird: Zuerst analysieren, dann Feld‑Formatierer schrittweise migrieren, Altlasten im Code entfernen und vor dem Deployment gründlich testen. Das glightbox-Drupal‑Modul macht den Großteil davon deklarativ — als Konfigurationsänderungen in der Admin‑Oberfläche statt durch individuellen Code.

Für Websites, die eine umfassendere Frontend‑Modernisierung anstreben — etwa den Übergang zu einer entkoppelten oder Headless‑Architektur, die Einführung eines modernen Themes (Olivero, Gin oder ein eigenes Design‑System) oder die Reduktion von JavaScript‑Payload — ist der Austausch von Colorbox durch GLightbox ein hervorragender, klar abgegrenzter Einstieg mit sichtbarem Mehrwert und minimalem Risiko.