Drupal: sostituire Colorbox con GLightbox

1 Introduzione

I plugin lightbox sono stati un punto fermo dei siti basati su Drupal per oltre un decennio. Consentono agli editor di visualizzare immagini, video e altri media in una sovrimpressione senza abbandonare la pagina corrente — uno schema che i visitatori si aspettano sui siti moderni e ricchi di contenuti multimediali.

Colorbox è stato storicamente la soluzione di riferimento nell’ecosistema Drupal. Il modulo contribuito colorbox si integra strettamente con i formatter dei campi immagine di Drupal, dispone di un’API matura ed è ampiamente conosciuto dalla community. Tuttavia, con l’evoluzione del web, Colorbox mostra la sua età: dipende da jQuery, distribuisce un payload più pesante ed è rimasto indietro rispetto alle moderne aspettative di accessibilità.

Entra in scena GLightbox — una libreria lightbox in JavaScript puro (zero dipendenze) con un’interfaccia raffinata, un solido supporto all’accessibilità e un ingombro ridotto. Il relativo modulo Drupal si integra in modo pulito con gli stessi campi immagine e le stesse entità media che in passato erano gestite da Colorbox.

Questo articolo ti guida attraverso l’intero processo di migrazione: dall’audit dell’attuale configurazione Colorbox all’installazione di GLightbox, dalla rimappatura dei formatter dei campi alla rimozione sicura del vecchio modulo, fino alla messa a punto della nuova esperienza per il tuo tema.

2 Colorbox vs GLightbox: perché migrare?

2.1 Limiti di Colorbox

Colorbox è stato creato in un’epoca diversa del web. La sua architettura riflette assunzioni che non sono più valide nello sviluppo Drupal moderno:

• Dipendenza da jQuery. Colorbox è un plugin jQuery — non può funzionare senza. Drupal core ha progressivamente ridotto la propria dipendenza da jQuery e molti temi orientati alle prestazioni caricano jQuery in modo lazy o non lo caricano affatto. Una dipendenza rigida da jQuery va contro questo obiettivo.
• Interfaccia e animazioni datate. Gli stili predefiniti di Colorbox risultano superati rispetto agli standard di design del periodo 2024–2026. Spesso è necessario personalizzare pesantemente il CSS solo per raggiungere un aspetto moderno di base.
• Lacune di accessibilità. Sebbene Colorbox abbia ricevuto nel tempo alcune correzioni sull’accessibilità, non è stato progettato avendo come obiettivo primario la conformità WCAG 2.1 AA. La gestione del focus, i ruoli ARIA e gli annunci per gli screen reader possono richiedere un lavoro aggiuntivo significativo.
• Velocità di manutenzione. La libreria jQuery Colorbox upstream riceve aggiornamenti poco frequenti. Per un progetto Drupal di lunga durata, fare affidamento su una dipendenza mantenuta lentamente introduce dei rischi.

2.2 Vantaggi di GLightbox

GLightbox affronta direttamente ciascuno dei punti critici sopra elencati:

• Nessuna dipendenza. JavaScript ES6+ puro; non richiede jQuery.
• UX moderna. Transizioni CSS fluide, gesture di swipe, navigazione da tastiera e un tema predefinito pulito che si integra bene con i design contemporanei.
• Accessibilità di primo livello. Il focus è trattenuto all’interno della lightbox, la navigazione con i tasti freccia funziona immediatamente e vengono applicate automaticamente semantiche ARIA corrette con role="dialog".
• Leggera. Il bundle minificato e gzip-pato è inferiore a 15 KB — circa 3× più leggero di una tipica configurazione Colorbox.
• Raggruppamento gallerie. Supporto nativo per gallerie raggruppate tramite l’attributo data-gallery, senza necessità di plugin aggiuntivi.
• Sviluppo attivo. Il progetto GLightbox su GitHub vede rilasci e correzioni di bug regolari.

3 Panoramica dell’ecosistema Drupal

Drupal core è impegnato da diversi anni in un percorso volto a ridurre l’uso di jQuery, orientandosi verso JavaScript vanilla e le moderne API dei browser. Questo approccio è evidente nella deprecazione di molti comportamenti basati su jQuery in Drupal 10+ e nell’incoraggiamento ai temi ad adottare strategie JavaScript più leggere.

Sul fronte contrib, sia Colorbox sia GLightbox dispongono di moduli Drupal dedicati su Drupal.org:

• colorbox — la scelta classica, con una profonda integrazione nei formatter dei campi immagine, in Views e nel sistema Media. È ancora ampiamente installato, ma riceve aggiornamenti meno frequenti.
• glightbox — un modulo contrib più recente che incapsula la libreria JavaScript GLightbox. Fornisce formatter per i campi Image e Media, supporto per Views e un modulo di configurazione per le opzioni più comuni di GLightbox.

4 Prepararsi alla migrazione

4.1 Analizzare l’utilizzo attuale di Colorbox

Prima di toccare qualsiasi configurazione, è fondamentale costruire un quadro completo di dove e in che modo Colorbox viene utilizzato nel sito:

1. Campi immagine. Vai su Struttura → Tipi di contenuto → [Tipo] → Gestisci visualizzazione per ogni tipo di contenuto e verifica se qualche campo immagine utilizza il formatter Colorbox. Annota gli stili immagine e le impostazioni delle didascalie.
2. Entità Media. Controlla le modalità di visualizzazione dei tipi di media in Struttura → Tipi di media. Ripeti l’operazione per ogni tipo di media che include immagini o video.
3. Views. Cerca le Views che includono campi immagine e verifica il formatter utilizzato. Colorbox può essere applicato anche tramite il plugin di formato “Colorbox” in Views.
4. Codice personalizzato. Cerca nei moduli e nei temi custom riferimenti a colorbox, .colorbox, Drupal.behaviors.colorbox e alla chiave di libreria colorbox/colorbox.

# Ricerca rapida nell’intera codebase (da eseguire dalla root di Drupal)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Tieni traccia di ogni occorrenza individuata. Tornerai su ciascuna di esse durante la fase di sostituzione.

4.2 Backup e considerazioni sull’ambiente

• Esporta la configurazione attiva: drush config:export
• Committa l’export nel sistema di controllo versione prima di iniziare
• Disabilita l’aggregazione CSS/JS durante la migrazione (Amministrazione → Prestazioni)
• Esegui un dump del database: drush sql:dump > pre-migration.sql
• Assicurati che la pipeline di deploy possa propagare le modifiche di configurazione su staging/produzione

5 Installare e abilitare GLightbox in Drupal

5.1 Installare la libreria JavaScript GLightbox

Il modulo Drupal GLightbox dipende dalla libreria upstream GLightbox JS. Esistono due modalità supportate per renderla disponibile.

Opzione A — Composer + Asset Packagist (Consigliata)

# Aggiungi Asset Packagist come repository (una sola volta per progetto)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Richiedi la libreria
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Aggiungi o verifica il percorso di installazione per npm-asset nella sezione extra.installer-paths del file composer.json:

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

Dopo aver eseguito composer install, la libreria sarà disponibile in web/libraries/glightbox/.

Opzione B — Posizionamento manuale

Scarica l’ultima release dalla pagina GLightbox GitHub releases e posiziona i file in modo che esistano i seguenti percorsi:

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

5.2 Installare e abilitare il modulo Drupal GLightbox

# Scarica il modulo
composer require drupal/glightbox

# Abilitalo
drush en glightbox -y

# Svuota la cache
drush cr

Naviga in Amministrazione → Configurazione → Media → GLightbox per verificare che la libreria venga rilevata correttamente ed esplorare le opzioni di configurazione globale.

6 Sostituire le funzionalità di Colorbox

6.1 Campi immagine

Questo è il caso d’uso più comune di Colorbox: un campo immagine in un tipo di contenuto che mostra una miniatura e apre l’immagine a dimensione completa in una lightbox.

1. Vai su Struttura → Tipi di contenuto → [Il tuo tipo] → Gestisci visualizzazione.
2. Individua il campo immagine. Nel menu a discesa Formato, cambia da Colorbox a GLightbox.
3. Clicca sull’icona delle impostazioni (⚙) per configurare il formatter. Imposta lo Stile immagine (miniatura mostrata nella pagina) e lo Stile immagine collegata (immagine caricata nella lightbox). Abilita le didascalie se necessario.
4. Salva la configurazione di visualizzazione e svuota la cache: drush cr.

Puoi anche esportare questa configurazione e applicarla tramite YAML. Di seguito un esempio di configurazione di un formatter di campo nel file YAML di visualizzazione di un tipo di contenuto:

# core.entity_view_display.node.article.default.yml (estratto)
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 e gallerie

Per i siti che utilizzano il sistema Media di Drupal, i passaggi di migrazione sono simili ma applicati alle modalità di visualizzazione dei tipi di media.

• Vai su Struttura → Tipi di media → [Tipo] → Gestisci visualizzazione.
• Cambia il formatter del campo sorgente dell’immagine da Colorbox a GLightbox.
• Per il raggruppamento delle gallerie, configura il campo ID galleria nelle impostazioni del formatter GLightbox. Tutti gli elementi che condividono lo stesso ID galleria saranno navigabili come gruppo all’interno della lightbox. Questo corrisponde direttamente all’attributo nativo data-gallery di GLightbox.

La mappatura delle didascalie è semplice: GLightbox legge l’attributo data-description. Il modulo Drupal consente di associarlo all’attributo title o alt dell’immagine, oppure a un valore di un campo personalizzato.

6.3 Integrazione con Views

Se le Views mostrano immagini con la formattazione Colorbox, aggiorna ciascuna View come segue:

1. Apri la View in Struttura → Views → [Nome della View] → Modifica.
2. Nella sezione Campi, fai clic sul campo immagine. Nel menu Formatter, passa da Colorbox a GLightbox.
3. Se l’integrazione Colorbox era gestita a livello di Formato (ad esempio tramite un plugin di formato “Colorbox”), passa a un formato standard come Lista non formattata o Griglia e applica invece il formatter GLightbox a livello di campo.
4. Salva e svuota la cache.

7 Rimuovere Colorbox in modo sicuro

Una volta migrati tutti i formatter e il codice personalizzato, puoi rimuovere Colorbox in tutta sicurezza. Segui questo ordine per evitare errori di dipendenza:

1. Disabilita il modulo Colorbox. La disabilitazione prima della disinstallazione consente a Drupal di eseguire le operazioni di pulizia definite in hook_uninstall().

   drush pm:uninstall colorbox -y

2. Rimuovi la dipendenza da composer.json.

   composer remove drupal/colorbox

3. Rimuovi la libreria JS di Colorbox da web/libraries/colorbox/ se era stata installata manualmente.
4. Pulisci il codice personalizzato. Cerca e rimuovi eventuali riferimenti residui alle classi CSS di Colorbox (.colorbox, .colorbox-load), ai behavior JavaScript (Drupal.behaviors.colorbox) o agli attachment di libreria (colorbox/colorbox).

5. Svuota tutte le cache ed esporta la configurazione.

   drush cr
   drush config:export

8 Personalizzazione e miglioramenti

8.1 Opzioni di configurazione di GLightbox

La pagina delle impostazioni globali di GLightbox (Amministrazione → Configurazione → Media → GLightbox) espone le opzioni più comunemente utilizzate. Queste corrispondono direttamente all’API JavaScript di GLightbox:

8.2 Theming e styling

GLightbox include un foglio di stile predefinito (glightbox.min.css) che fornisce un design pulito con overlay scuro. È possibile sovrascriverlo nel proprio tema senza modificare il file della libreria:

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

/* Cambia lo sfondo dell’overlay */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* Stile dell’area didascalie */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* Ingrandisce le frecce di navigazione */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

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

Collega il foglio di stile di override nel file .libraries.yml del tuo tema:

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

Quindi aggancialo globalmente in mytheme.info.yml:

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

8.3 Casi d’uso avanzati

Aggancio programmatico tramite #attached

Puoi agganciare la libreria GLightbox a qualsiasi render array in un modulo personalizzato o in un hook di preprocess:

// In una funzione preprocess o nel build() di un blocco custom
$build['#attached']['library'][] = 'glightbox/glightbox';

// Passa override di configurazione alle impostazioni JS
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Trigger personalizzati nei template Twig

Per creare manualmente un trigger GLightbox in un template Twig, aggiungi gli attributi corretti. GLightbox intercetta qualsiasi elemento con class="glightbox" (o il selector configurato):

{# Apre una singola immagine #}
<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>

{# Gruppo galleria — tutti gli elementi con lo stesso data-gallery si aprono insieme #}
{% 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 per inizializzazione personalizzata

Se hai bisogno di inizializzare GLightbox con opzioni non esposte dall’interfaccia di amministrazione del modulo, utilizza un behavior Drupal personalizzato:

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

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // Inizializza una sola volta per contesto
      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 Test e controllo qualità

Dopo aver completato la migrazione, esegui la seguente checklist di QA prima di distribuire in produzione:

Test funzionali

• Le immagini si aprono nella lightbox al clic in tutti i tipi di contenuto interessati
• La navigazione della galleria (frecce precedente/successivo, frecce da tastiera) funziona correttamente
• Le didascalie vengono visualizzate e corrispondono al valore del campo previsto
• I contenuti video (YouTube, Vimeo, locali) partono automaticamente e si chiudono correttamente
• La chiusura della lightbox (pulsante ✕, tasto Esc, clic esterno) ripristina correttamente il focus

Test cross-browser

• Chrome/Edge (Chromium), Firefox, Safari (macOS e iOS)
• Verifica che le transizioni CSS vengano renderizzate correttamente in tutti i browser testati

Test su dispositivi mobili e touch

• Swipe a sinistra/destra per navigare tra gli elementi della galleria
• Pinch-to-zoom sulle immagini (se abilitato)
• L’overlay copre correttamente il viewport su schermi di piccole dimensioni

Verifiche di accessibilità

• Il tasto Tab cicla tra i controlli della lightbox (chiudi, precedente, successivo)
• Il focus ritorna all’elemento di attivazione dopo la chiusura
• Lo screen reader annuncia il dialogo e il suo contenuto (test con NVDA o VoiceOver)
• Esegui un audit di accessibilità con axe DevTools o Lighthouse — obiettivo: zero errori critici

Prestazioni

• Riabilita l’aggregazione CSS/JS e verifica che GLightbox continui a inizializzarsi correttamente
• Esegui un audit delle prestazioni con Lighthouse e confrontalo con la baseline di Colorbox
• Verifica l’assenza di errori JavaScript nella console su tutte le pagine testate

10 Problemi comuni e risoluzione

Le immagini non si aprono nella lightbox

Sintomo: Facendo clic sull’immagine si viene reindirizzati all’URL collegato invece di aprire GLightbox.

• Verifica che la libreria GLightbox venga caricata: apri gli strumenti di sviluppo del browser → scheda Network, filtra per glightbox. Se non compare, controlla che i file della libreria esistano in web/libraries/glightbox/dist/.
• Assicurati che l’aggregazione CSS/JS funzioni correttamente; prova a disabilitarla temporaneamente per isolare eventuali problemi legati all’aggregazione.
• Controlla l’HTML renderizzato per verificare che l’elemento di attivazione abbia l’attributo class="glightbox" (o il selettore personalizzato configurato).

Didascalie mancanti o gallerie non funzionanti

Sintomo: Le didascalie sono vuote o la navigazione della galleria salta alcuni elementi.

• Ispeziona i tag anchor renderizzati: verifica che data-description sia valorizzato e che i valori di data-gallery corrispondano tra gli elementi raggruppati.
• Controlla che l’impostazione del formatter Sorgente della didascalia punti a un campo non vuoto.
• Per il raggruppamento delle gallerie, verifica che l’ID galleria sia coerente; gli ID generati tramite token possono risolversi in stringhe vuote se il modulo Token non è installato.

Conflitti con altre librerie JavaScript

Sintomo: GLightbox si inizializza solo parzialmente o genera errori nella console.

• Verifica che la libreria GLightbox non venga caricata più volte (modulo + aggancio manuale nel tema).
• Assicurati che nessun’altra libreria stia sovrascrivendo window.GLightbox.
• Se il tuo tema utilizza un bundler JavaScript, verifica che GLightbox non venga incluso anche lì oltre al sistema di asset di Drupal.

Problemi di cache e aggregazione

Sintomo: GLightbox funziona in sviluppo ma non in produzione.

• Esegui drush cr in produzione dopo aver distribuito le modifiche di configurazione.
• Verifica che la directory web/libraries/glightbox/ venga correttamente inclusa nel deploy — a volte è esclusa da regole .gitignore che colpiscono la directory libraries/. Valuta l’utilizzo di composer install --no-dev nella pipeline CI/CD per assicurarti che la libreria venga installata.
• Se l’aggregazione CSS comprime il foglio di stile GLightbox in modo da rompere la specificità dei selettori, aggancia il file di override in una posizione successiva nell’ordine di caricamento degli asset.

# Svuota tutte le cache in produzione (se Drush è disponibile)
drush @prod cr

# Verifica che il file della libreria esista
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Conclusione

Migrare da Colorbox a GLightbox rappresenta un passo significativo di modernizzazione frontend per qualsiasi progetto Drupal. I benefici sono concreti:

• Eliminare la dipendenza runtime da jQuery nel percorso della lightbox
• Offrire ai visitatori un’esperienza più veloce e leggera
• Ottenere la conformità all’accessibilità pronta all’uso senza patch personalizzate
• Allinearsi alla direzione di Drupal core verso JavaScript vanilla
• Ridurre il carico di manutenzione a lungo termine grazie a una libreria sviluppata attivamente

La migrazione in sé comporta pochi rischi se affrontata in maniera metodica: prima l’audit, poi la migrazione dei formatter dei campi uno alla volta, la pulizia del codice legacy e infine test approfonditi prima del deploy. Il modulo Drupal glightbox rende gran parte di questo processo dichiarativo — modifiche di configurazione nell’interfaccia di amministrazione anziché codice personalizzato.

Per i siti che stanno affrontando una modernizzazione frontend più ampia — passando a un’architettura decoupled o headless, adottando un tema moderno (Olivero, Gin o un design system personalizzato) o riducendo il peso JavaScript — sostituire Colorbox con GLightbox è un eccellente punto di partenza, circoscritto ma ad alto impatto, che produce risultati visibili con un rischio minimo.