Drupal: Vervang Colorbox door GLightbox

1 Introductie

Lightbox-plugins zijn al meer dan tien jaar een vaste waarde op Drupal‑websites. Ze stellen editors in staat om afbeeldingen, video’s en andere media in een overlay te tonen zonder de huidige pagina te verlaten — een patroon dat bezoekers verwachten op moderne, media‑rijke websites.

Colorbox is historisch gezien dé standaardoplossing binnen het Drupal‑ecosysteem. De bijgedragen colorbox-module integreert nauw met Drupal’s afbeeldingsveld‑formatters, beschikt over een volwassen API en geniet brede bekendheid binnen de community. Naarmate het web zich echter heeft ontwikkeld, begint Colorbox zijn leeftijd te tonen: het is afhankelijk van jQuery, levert een zwaardere payload en blijft achter bij hedendaagse toegankelijkheidsverwachtingen.

Maak kennis met GLightbox — een pure vanilla‑JavaScript lightbox‑bibliotheek (zonder afhankelijkheden) met een gepolijste UI, robuuste ondersteuning voor toegankelijkheid en een lichtgewicht footprint. De bijbehorende Drupal‑module integreert netjes met dezelfde afbeeldingsvelden en media‑entiteiten die voorheen door Colorbox werden afgehandeld.

Dit artikel begeleidt je door de volledige migratie: van het auditen van je huidige Colorbox‑configuratie tot het installeren van GLightbox, het opnieuw toewijzen van veld‑formatters, het veilig verwijderen van de oude module en het finetunen van de nieuwe ervaring binnen je theme.

2 Colorbox vs GLightbox: waarom migreren?

2.1 Beperkingen van Colorbox

Colorbox is ontwikkeld in een ander tijdperk van het web. De architectuur weerspiegelt aannames die in moderne Drupal‑ontwikkeling niet langer gelden:

• Afhankelijkheid van jQuery. Colorbox is een jQuery‑plugin en kan niet functioneren zonder jQuery. Drupal core heeft zijn afhankelijkheid van jQuery de afgelopen jaren steeds verder afgebouwd, en veel performance‑gerichte themes laden jQuery pas laat of helemaal niet. Een harde jQuery‑afhankelijkheid werkt dit tegen.
• Verouderde UI en animaties. De standaard Colorbox‑stijl voelt gedateerd vergeleken met ontwerptrends van 2024–2026. Vaak is ingrijpende CSS‑maatwerk nodig om een minimaal modern uiterlijk te bereiken.
• Toegankelijkheidslacunes. Hoewel Colorbox in de loop der jaren enkele toegankelijkheidsupdates heeft gekregen, is het niet ontworpen met WCAG 2.1 AA als primair doel. Focus‑trapping, ARIA‑rollen en screenreader‑aankondigingen vereisen vaak aanzienlijk extra werk.
• Onderhoudssnelheid. De upstream jQuery‑Colorbox‑bibliotheek krijgt onregelmatig updates. Voor langlopende Drupal‑projecten brengt afhankelijkheid van een traag onderhouden library extra risico met zich mee.

2.2 Voordelen van GLightbox

GLightbox pakt elk van bovenstaande pijnpunten rechtstreeks aan:

• Geen afhankelijkheden. Pure ES6+ JavaScript; geen jQuery nodig.
• Moderne UX. Vloeiende CSS‑transities, swipe‑gebaren, toetsenbordnavigatie en een strak standaardthema dat goed aansluit bij hedendaagse designs.
• Eersteklas toegankelijkheid. Focus wordt automatisch binnen de lightbox gehouden, toetsenbord‑navigatie met pijltjestoetsen werkt out‑of‑the‑box en correcte ARIA‑semantiek met role="dialog" wordt automatisch toegepast.
• Lichtgewicht. De geminificeerde en ge‑gzipte bundel is kleiner dan 15 KB — ongeveer drie keer lichter dan een typische Colorbox‑setup.
• Galerij‑groepering. Ingebouwde ondersteuning voor gegroepeerde galerijen via het data-gallery-attribuut, zonder extra plugins.
• Actieve ontwikkeling. Het GLightbox‑project op GitHub ontvangt regelmatig releases en bugfixes.

3 Overzicht van het Drupal‑ecosysteem

Drupal core is al meerdere jaren bezig met het terugdringen van zijn jQuery‑gebruik en beweegt zich richting vanilla JavaScript en moderne browser‑API’s. Dit zien we terug in het afschaffen van veel jQuery‑gebaseerde behaviors in Drupal 10+ en in de aansporing aan themes om slankere JavaScript‑strategieën te hanteren.

Aan de contrib‑zijde hebben zowel Colorbox als GLightbox eigen Drupal‑modules op Drupal.org:

• colorbox — de klassieke keuze, met diepe integratie in afbeeldingsveld‑formatters, Views en het mediasysteem. Nog steeds wijdverbreid geïnstalleerd, maar ontvangt minder updates.
• glightbox — een nieuwere contrib‑module die de GLightbox‑JS‑bibliotheek omhult. Biedt Image‑ en Media‑veld‑formatters, Views‑ondersteuning en een instellingenpagina voor gangbare GLightbox‑opties.

4 Voorbereiding van de migratie

4.1 Audit van het huidige Colorbox‑gebruik

Breng voordat je configuraties wijzigt een volledig beeld in kaart van waar en hoe Colorbox op je site wordt gebruikt:

1. Afbeeldingsvelden. Ga naar Structuur → Contenttypes → [Type] → Weergave beheren voor elk contenttype en controleer of afbeeldingsvelden de Colorbox-formatter gebruiken. Noteer de afbeeldingsstijlen en caption‑instellingen.
2. Media‑entiteiten. Controleer de weergavemodi van mediatypes via Structuur → Mediatypes. Herhaal dit voor elk mediatype met afbeeldingen of video.
3. Views. Zoek Views die afbeeldingsvelden bevatten en controleer welke formatter wordt gebruikt. Colorbox kan ook toegepast zijn via de Views‑formatplugin “Colorbox”.
4. Maatwerkcode. Doorzoek je custom modules en themes op verwijzingen naar colorbox, .colorbox, Drupal.behaviors.colorbox en de library‑sleutel colorbox/colorbox.

# Snelle zoekactie door je codebase (uitvoeren vanaf de Drupal-root)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Houd elke gevonden locatie bij. Je zult elke ervan opnieuw langslopen tijdens de vervangingsfase.

4.2 Back-up en omgevings­overwegingen

• Actieve configuratie exporteren: drush config:export
• De export committen in versiebeheer vóór de start
• CSS/JS‑aggregatie uitschakelen tijdens de migratie (Beheer → Prestaties)
• Een database‑dump maken: drush sql:dump > pre-migration.sql
• Controleren of je deployment‑pipeline configuratie­wijzigingen kan uitrollen naar staging/productie

5 GLightbox installeren en inschakelen in Drupal

5.1 De GLightbox JavaScript‑bibliotheek installeren

De Drupal GLightbox‑module is afhankelijk van de upstream GLightbox JS‑bibliotheek. Er zijn twee ondersteunde manieren om deze beschikbaar te maken.

Optie A — Composer + Asset Packagist (aanbevolen)

# Asset Packagist als repository toevoegen (eenmalig per project)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# De library vereisen
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Voeg toe of controleer het installer‑pad voor npm-asset in de extra.installer-paths-sectie van je composer.json:

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

Na het uitvoeren van composer install wordt de library geplaatst in web/libraries/glightbox/.

Optie B — Handmatige plaatsing

Download de laatste release via de GLightbox GitHub‑releases en plaats de bestanden zodat de volgende paden bestaan:

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

5.2 De GLightbox Drupal‑module installeren en inschakelen

# De module downloaden
composer require drupal/glightbox

# Inschakelen
drush en glightbox -y

# Cache legen
drush cr

Ga naar Beheer → Configuratie → Media → GLightbox om te bevestigen dat de library wordt gedetecteerd en om de globale configuratie­opties te bekijken.

6 Colorbox-functionaliteit vervangen

6.1 Afbeeldingsvelden

Dit is het meest voorkomende gebruiksscenario van Colorbox: een afbeeldingsveld binnen een contenttype dat een thumbnail toont en bij aanklikken de afbeelding op volledige grootte opent in een lightbox.

1. Ga naar Structuur → Contenttypes → [Uw type] → Weergave beheren.
2. Zoek het afbeeldingsveld. Kies in de vervolgkeuzelijst Opmaak voor GLightbox in plaats van Colorbox.
3. Klik op het instellingen‑icoon (⚙) om de formatter te configureren. Stel de Afbeeldingsstijl in (de thumbnail op de pagina) en de Gekoppelde afbeeldingsstijl (de afbeelding die in de lightbox wordt geladen). Schakel eventueel bijschriften in.
4. Sla de weergave-instellingen op en leeg de cache: drush cr.

Je kunt deze configuratie ook exporteren en toepassen via YAML. Hieronder een voorbeeld van een veld‑formatterconfiguratie in een contenttype‑weergave‑YAML:

# core.entity_view_display.node.article.default.yml (uittreksel)
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 en galerijen

Voor sites die het Media‑systeem van Drupal gebruiken, zijn de migratiestappen vergelijkbaar, maar toegepast op de weergavemodi van mediatypes.

• Ga naar Structuur → Mediatypes → [Type] → Weergave beheren.
• Wijzig de formatter van het afbeeldingsbronveld van Colorbox naar GLightbox.
• Voor galerij‑groepering stel je het veld Galerij‑ID in via de GLightbox‑formatterinstellingen. Alle items met dezelfde galerij‑ID zijn binnen de lightbox als groep navigeerbaar. Dit komt rechtstreeks overeen met het native data-gallery-attribuut van GLightbox.

Het koppelen van bijschriften is eenvoudig: GLightbox leest het data-description-attribuut. De Drupal‑module laat je dit koppelen aan het title- of alt-attribuut van de afbeelding, of aan een aangepaste veldwaarde.

6.3 Integratie met Views

Als Views afbeeldingen met Colorbox‑opmaak weergeven, werk elke View als volgt bij:

1. Open de View via Structuur → Views → [Naam van de View] → Bewerken.
2. Klik onder Velden op het afbeeldingsveld. Kies in de vervolgkeuzelijst Formatter voor GLightbox in plaats van Colorbox.
3. Als de Colorbox‑integratie werd toegepast op Opmaak-niveau (bijvoorbeeld via een “Colorbox”-formatplugin), schakel dan over naar een standaardopmaak zoals Onopgemaakte lijst of Raster en pas de GLightbox‑formatter toe op veldniveau.
4. Sla op en leeg de cache.

4.2 Back-up en omgevings­overwegingen

• Actieve configuratie exporteren: drush config:export
• De export committen in versiebeheer vóór de start
• CSS/JS‑aggregatie uitschakelen tijdens de migratie (Beheer → Prestaties)
• Een database‑dump maken: drush sql:dump > pre-migration.sql
• Controleren of je deployment‑pipeline configuratie­wijzigingen kan uitrollen naar staging/productie

5 GLightbox installeren en inschakelen in Drupal

5.1 De GLightbox JavaScript‑bibliotheek installeren

De Drupal GLightbox‑module is afhankelijk van de upstream https://github.com/biati-digital/glightboxGLightbox JS‑bibliotheek. Er zijn twee ondersteunde manieren om deze beschikbaar te maken.

Optie A — Composer + Asset Packagist (aanbevolen)

# Asset Packagist als repository toevoegen (eenmalig per project)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# De library vereisen
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Voeg toe of controleer het installer‑pad voor npm-asset in de extra.installer-paths-sectie van je composer.json:

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

Na het uitvoeren van composer install wordt de library geplaatst in web/libraries/glightbox/.

Optie B — Handmatige plaatsing

Download de laatste release via de https://github.com/biati-digital/glightbox/releasesGLightbox GitHub‑releases en plaats de bestanden zodat de volgende paden bestaan:

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

5.2 De GLightbox Drupal‑module installeren en inschakelen

# De module downloaden
composer require drupal/glightbox

# Inschakelen
drush en glightbox -y

# Cache legen
drush cr

Ga naar Beheer → Configuratie → Media → GLightbox om te bevestigen dat de library wordt gedetecteerd en om de globale configuratie­opties te bekijken.

8.2 Theming en styling

GLightbox wordt geleverd met een standaard stylesheet (glightbox.min.css) die een strak ontwerp met donkere overlay biedt. Overschrijf deze in je theme zonder het library‑bestand zelf aan te passen:

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

/* Achtergrond van de overlay aanpassen */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

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

/* Navigatiepijlen vergroten */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* Variant voor lichte modus */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

Koppel het override‑stylesheet in het .libraries.yml-bestand van je theme:

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

Koppel het vervolgens globaal in mytheme.info.yml:

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

8.3 Geavanceerde use‑cases

Programmatisch koppelen via #attached

Je kunt de GLightbox‑library koppelen aan elke render‑array in een custom module of preprocess‑hook:

// In een preprocess‑functie of custom block build()
$build['#attached']['library'][] = 'glightbox/glightbox';

// Configuratie‑overrides doorgeven aan JS‑settings
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Aangepaste triggers in Twig‑templates

Om handmatig een GLightbox‑trigger te maken in een Twig‑template, voeg je de juiste attributen toe. GLightbox pikt elk element op met class="glightbox" (of de door jou geconfigureerde selector):

{# Eén enkele afbeelding openen #}
<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>

{# Galerijgroep — alle items met dezelfde data-gallery openen samen #}
{% 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 voor aangepaste initialisatie

Als je GLightbox wilt initialiseren met opties die niet beschikbaar zijn via de admin‑UI van de module, gebruik dan een custom Drupal‑behavior:

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

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // Slechts één keer per context initialiseren
      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 Testen en kwaliteitscontrole

Na het voltooien van de migratie doorloop je de onderstaande QA‑checklist voordat je naar productie deployt:

Functionele tests

• Afbeeldingen openen correct in de lightbox bij klikken, op alle betrokken contenttypes
• Galerijnavigatie (vorige/volgende pijlen, pijltjestoetsen) werkt correct
• Bijschriften worden weergegeven en komen overeen met de verwachte veldwaarde
• Video‑items (YouTube, Vimeo, lokaal) spelen automatisch af en sluiten correct
• Het sluiten van de lightbox (✕‑knop, Escape‑toets, klik buiten de overlay) herstelt de focus correct

Cross‑browser tests

• Chrome/Edge (Chromium), Firefox en Safari (macOS en iOS)
• Controleren of CSS‑transities correct renderen in alle geteste browsers

Mobiel‑ en touch‑testen

• Naar links/rechts swipen om door galerijitems te navigeren
• Pinch‑to‑zoom op afbeeldingen (indien ingeschakeld)
• De overlay bedekt het volledige viewport correct op kleine schermen

Toegankelijkheidscontroles

• De Tab‑toets doorloopt alle lightbox‑bedieningen (sluiten, vorige, volgende)
• Focus keert terug naar het trigger‑element na het sluiten
• Screenreaders kondigen het dialoogvenster en de inhoud aan (testen met NVDA of VoiceOver)
• Axe DevTools of Lighthouse toegankelijkheidsaudit uitvoeren — doel: nul kritieke fouten

Prestatie

• CSS/JS‑aggregatie opnieuw inschakelen en controleren of GLightbox nog correct initialiseert
• Een Lighthouse‑prestatieaudit uitvoeren en vergelijken met de Colorbox‑baseline
• Controleren of er geen JavaScript‑consolefouten optreden op geteste pagina’s

10 Veelvoorkomende problemen en troubleshooting

Afbeeldingen openen niet in de lightbox

Symptoom: Bij het klikken navigeert de afbeelding naar de gekoppelde URL in plaats van GLightbox te openen.

• Controleer of de GLightbox‑library wordt geladen: open browser‑DevTools → Network‑tab en filter op glightbox. Ontbreekt deze, controleer dan of de library‑bestanden bestaan in web/libraries/glightbox/dist/.
• Controleer of CSS/JS‑aggregatie correct werkt; schakel deze tijdelijk uit om aggregatie‑gerelateerde problemen te isoleren.
• Inspecteer de gegenereerde HTML en controleer of het trigger‑element het attribuut class="glightbox" bevat (of de aangepaste selector die je hebt ingesteld).

Ontbrekende bijschriften of gebroken galerijen

Symptoom: Bijschriften zijn leeg of galerijnavigatie slaat items over.

• Inspecteer de gegenereerde anchor‑tags: controleer of data-description is gevuld en of data-gallery-waarden overeenkomen binnen gegroepeerde items.
• Controleer of de formatterinstelling Bron van bijschrift verwijst naar een niet‑leeg veld.
• Voor galerij‑groepering: verifieer dat de galerij‑ID consistent is; token‑gegenereerde ID’s kunnen leeg zijn als de Token‑module niet is geïnstalleerd.

Conflicten met andere JavaScript‑libraries

Symptoom: GLightbox initialiseert deels of genereert consolefouten.

• Controleer op dubbele laadacties van de GLightbox‑library (module + handmatige theme‑koppeling).
• Verifieer dat geen andere library window.GLightbox overschrijft.
• Als je theme een JS‑bundler gebruikt, zorg ervoor dat GLightbox niet dubbel wordt gebundeld naast Drupal’s asset‑systeem.

Cache‑ en aggregatieproblemen

Symptoom: GLightbox werkt in development maar faalt in productie.

• Voer drush cr uit op productie na het deployen van configuratiewijzigingen.
• Controleer of web/libraries/glightbox/ correct is gedeployed — deze map wordt soms uitgesloten door .gitignore-regels voor de libraries/-directory. Overweeg composer install --no-dev in je CI/CD‑pipeline.
• Als CSS‑aggregatie de GLightbox‑stylesheet op een manier comprimeert die selector‑specificiteit breekt, laad je override‑bestand later in de asset‑volgorde.

# Cache legen op productie (indien Drush beschikbaar is)
drush @prod cr

# Controleren of het library‑bestand aanwezig is
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Conclusie

De migratie van Colorbox naar GLightbox is een betekenisvolle frontend‑moderniseringsstap voor elk Drupal‑project. De voordelen zijn duidelijk en concreet:

• Het verwijderen van de jQuery‑runtime‑afhankelijkheid uit je lightbox‑pad
• Een snellere en lichtere gebruikerservaring voor bezoekers
• Directe toegankelijkheidscompliance zonder maatwerk‑patches
• Afstemming op de richting van Drupal core richting vanilla JavaScript
• Lagere onderhoudslast op lange termijn dankzij een actief onderhouden library

De migratie zelf is laag‑risico wanneer je deze methodisch aanpakt: eerst auditen, daarna formatterinstellingen één voor één migreren, legacy‑code opschonen en grondig testen vóór deployment. De glightbox-Drupal‑module maakt het grootste deel hiervan declaratief — configuratiewijzigingen via de beheerinterface in plaats van custom code.

Voor sites die bezig zijn met bredere frontend‑modernisering — zoals een overstap naar een decoupled of headless architectuur, het adopteren van een modern theme (Olivero, Gin of een eigen design system), of het terugdringen van JavaScript‑gewicht — is het vervangen van Colorbox door GLightbox een uitstekende, afgebakende eerste stap die zichtbare resultaten oplevert met minimale risico’s.