Drupal: Reemplazar Colorbox por GLightbox

1 Introducción

Los plugins de lightbox han sido un componente básico de los sitios web impulsados por Drupal durante más de una década. Permiten a los editores mostrar imágenes, videos y otros medios en una superposición sin abandonar la página actual — un patrón que los visitantes esperan en sitios modernos ricos en contenido multimedia.

Colorbox ha sido históricamente la solución de referencia en el ecosistema de Drupal. El módulo contribuido colorbox se integra estrechamente con los formateadores de campos de imagen de Drupal, tiene una API madura y goza de una amplia familiaridad en la comunidad. Sin embargo, a medida que la web ha evolucionado, Colorbox muestra su antigüedad: depende de jQuery, incluye una carga más pesada y queda rezagado frente a las expectativas modernas de accesibilidad.

Entra en escena GLightbox — una biblioteca de lightbox en JavaScript puro (sin dependencias) con una interfaz pulida, un sólido soporte de accesibilidad y un tamaño reducido. Su módulo correspondiente en Drupal se integra limpiamente con los mismos campos de imagen y entidades de medios que Colorbox solía manejar.

Este artículo te guía a través de toda la migración: desde auditar tu configuración actual de Colorbox hasta instalar GLightbox, volver a mapear los formateadores de campo, eliminar el módulo antiguo de forma segura y ajustar la nueva experiencia para tu tema.

2 Colorbox vs GLightbox: ¿Por qué migrar?

2.1 Limitaciones de Colorbox

Colorbox fue creado en una era diferente de la web. Su arquitectura refleja suposiciones que ya no se aplican en el desarrollo moderno de Drupal:

• Dependencia de jQuery. Colorbox es un plugin de jQuery — no puede ejecutarse sin él. El núcleo de Drupal ha ido reduciendo progresivamente su dependencia de jQuery, y muchos temas orientados al rendimiento lo cargan de forma diferida o no lo usan en absoluto. Una dependencia estricta de jQuery va en contra de este objetivo.
• Interfaz y animaciones anticuadas. Los estilos predeterminados de Colorbox se sienten obsoletos en comparación con los estándares de diseño de 2024–2026. A menudo se requiere una personalización intensiva de CSS solo para lograr un aspecto moderno básico.
• Limitaciones de accesibilidad. Aunque Colorbox ha recibido algunos parches de accesibilidad a lo largo de los años, no fue diseñado teniendo como objetivo principal WCAG 2.1 AA. La gestión del foco, roles ARIA y anuncios para lectores de pantalla pueden requerir trabajo adicional considerable.
• Velocidad de mantenimiento. La biblioteca jQuery Colorbox recibe actualizaciones con poca frecuencia. Para proyectos Drupal a largo plazo, depender de una librería con mantenimiento lento introduce riesgos.

2.2 Ventajas de GLightbox

GLightbox aborda directamente cada uno de los problemas anteriores:

• Sin dependencias. JavaScript ES6+ puro; no requiere jQuery.
• Experiencia de usuario moderna. Transiciones CSS suaves, gestos táctiles, navegación por teclado y un tema predeterminado limpio que se integra bien con diseños actuales.
• Accesibilidad de primer nivel. El foco se mantiene dentro del lightbox, la navegación con teclas de flecha funciona de forma nativa y se aplican automáticamente roles ARIA adecuados como role="dialog".
• Ligero. El paquete minificado y comprimido es inferior a 15 KB — aproximadamente 3× más ligero que una configuración típica de Colorbox.
• Agrupación de galerías. Soporte nativo para galerías agrupadas mediante el atributo data-gallery, sin necesidad de plugins adicionales.
• Desarrollo activo. El proyecto GLightbox en GitHub tiene publicaciones regulares y correcciones de errores.

3 Visión general del ecosistema de Drupal

El núcleo de Drupal ha estado en un proceso de varios años para reducir su dependencia de jQuery, avanzando hacia JavaScript puro y APIs modernas del navegador. Esto se refleja en la descontinuación de muchos comportamientos basados en jQuery en Drupal 10+ y en el impulso para que los temas adopten estrategias JavaScript más ligeras.

En el lado de los módulos contribuidos, tanto Colorbox como GLightbox tienen módulos dedicados en Drupal.org:

• colorbox — la opción clásica, con integración profunda en formateadores de campos de imagen, Views y el sistema de medios. Sigue siendo ampliamente utilizado, pero recibe menos actualizaciones.
• glightbox — un módulo contrib más reciente que envuelve la librería JavaScript GLightbox. Proporciona formateadores para campos de Imagen y Media, soporte para Views y un formulario de configuración para opciones comunes de GLightbox.

4 Preparación para la migración

4.1 Auditoría del uso actual de Colorbox

Antes de modificar cualquier configuración, construye una visión completa de dónde y cómo se utiliza Colorbox en tu sitio:

1. Campos de imagen. Visita Estructura → Tipos de contenido → [Tipo] → Gestionar visualización para cada tipo de contenido y comprueba si algún campo de imagen utiliza el formateador Colorbox. Anota los estilos de imagen y la configuración de captions.
2. Entidades de medios. Revisa los modos de visualización de cada tipo de media en Estructura → Tipos de medios.
3. Views. Busca Views que incluyan campos de imagen y verifica el formateador utilizado. Colorbox también puede estar aplicado mediante el plugin de formato "Colorbox" en Views.
4. Código personalizado. Busca en tus módulos y temas personalizados referencias a colorbox, .colorbox, Drupal.behaviors.colorbox y la librería colorbox/colorbox.

# Búsqueda rápida en todo el código (ejecutar desde la raíz de Drupal)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Toma nota de cada ubicación encontrada. Volverás a cada una durante la fase de reemplazo.

4.2 Copias de seguridad y consideraciones de entorno

• Exporta la configuración activa: drush config:export
• Confirma el export en el control de versiones antes de comenzar
• Desactiva la agregación de CSS/JS durante la migración (Admin → Rendimiento)
• Realiza un volcado de base de datos: drush sql:dump > pre-migration.sql
• Asegúrate de que tu pipeline de despliegue pueda aplicar cambios de configuración en staging/producción

5 Instalación y activación de GLightbox en Drupal

5.1 Instalar la biblioteca JavaScript de GLightbox

El módulo GLightbox para Drupal depende de la librería externa GLightbox JS. Existen dos formas soportadas de proporcionarla.

Opción A — Composer + Asset Packagist (Recomendado)

# Añadir Asset Packagist como repositorio (una sola vez por proyecto)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Requerir la librería
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Añade o confirma la ruta de instalación para npm-asset en la sección extra.installer-paths de tu archivo composer.json:

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

Después de ejecutar composer install, la librería se ubicará en web/libraries/glightbox/.

Opción B — Instalación manual

Descarga la última versión desde la página de releases de GLightbox en GitHub y coloca los archivos de forma que existan las siguientes rutas:

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

5.2 Instalar y habilitar el módulo GLightbox para Drupal

# Descargar el módulo
composer require drupal/glightbox

# Habilitarlo
drush en glightbox -y

# Limpiar caché
drush cr

Navega a Admin → Configuración → Medios → GLightbox para confirmar que la librería ha sido detectada y explorar las opciones globales de configuración.

6 Reemplazando la funcionalidad de Colorbox

6.1 Campos de imagen

Este es el caso de uso más común de Colorbox: un campo de imagen en un tipo de contenido que muestra una miniatura que abre la imagen completa en un lightbox.

1. Ve a Estructura → Tipos de contenido → [Tu tipo] → Gestionar visualización.
2. Localiza el campo de imagen. En el desplegable Formato, cámbialo de Colorbox a GLightbox.
3. Haz clic en el icono de configuración (⚙) para ajustar el formateador. Define el estilo de imagen (miniatura mostrada) y el estilo de imagen enlazada (imagen cargada dentro del lightbox). Activa captions si lo deseas.
4. Guarda la configuración y limpia la caché: drush cr.

También puedes exportar esta configuración y aplicarla mediante YAML. Ejemplo:

# core.entity_view_display.node.article.default.yml (fragmento)
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 y galerías

Para sitios que utilizan el sistema de Media de Drupal, los pasos de migración son similares, pero se aplican a los modos de visualización de los tipos de medios.

• Ve a Estructura → Tipos de medios → [Tipo] → Gestionar visualización.
• Cambia el formateador del campo de origen de imagen de Colorbox a GLightbox.
• Para la agrupación de galerías, configura el campo ID de galería en los ajustes del formateador de GLightbox. Todos los elementos que compartan el mismo ID podrán navegarse como grupo dentro del lightbox. Esto corresponde directamente al atributo nativo data-gallery de GLightbox.

El mapeo de captions es sencillo: GLightbox utiliza el atributo data-description. El módulo de Drupal permite asignarlo al atributo title o alt de la imagen, o a un valor de campo personalizado.

6.3 Integración con Views

Si tus Views muestran imágenes usando Colorbox, actualiza cada vista de la siguiente manera:

1. Abre la vista en Estructura → Views → [Nombre de la vista] → Editar.
2. En Campos, haz clic en el campo de imagen. En el desplegable Formateador, cámbialo de Colorbox a GLightbox.
3. Si la integración de Colorbox estaba aplicada a nivel de Formato (por ejemplo, mediante un plugin de formato “Colorbox”), cámbialo a un formato estándar como Lista sin formato o Cuadrícula y aplica GLightbox a nivel de campo.
4. Guarda y limpia la caché.

7 Eliminación segura de Colorbox

Una vez que todos los formateadores y el código personalizado han sido migrados, puedes eliminar Colorbox de forma segura. Sigue este orden para evitar errores de dependencias:

1. Deshabilitar el módulo Colorbox. Desactivarlo antes de desinstalar permite que Drupal ejecute su limpieza mediante hook_uninstall().

   drush pm:uninstall colorbox -y

2. Eliminarlo de composer.json.

   composer remove drupal/colorbox

3. Eliminar la librería JavaScript de Colorbox de web/libraries/colorbox/ si fue añadida manualmente.
4. Limpiar código personalizado. Elimina cualquier referencia restante a clases CSS (.colorbox, .colorbox-load), behaviors JS (Drupal.behaviors.colorbox) o librerías (colorbox/colorbox).

5. Limpiar cachés y exportar configuración.

   drush cr
   drush config:export

8 Personalización y mejoras

8.1 Opciones de configuración de GLightbox

La página global de configuración de GLightbox (Admin → Configuración → Medios → GLightbox) expone las opciones más comunes. Estas corresponden directamente a la API JavaScript de GLightbox:

8.2 Tematización y estilos

GLightbox incluye una hoja de estilos por defecto (glightbox.min.css) con un diseño limpio de overlay oscuro. Puedes sobrescribirla en tu tema sin modificar la librería original:

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

/* Cambiar fondo del overlay */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* Estilo del área de caption */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* Aumentar tamaño de flechas */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

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

Adjunta la hoja de estilos en .libraries.yml:

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

Y luego inclúyela globalmente en mytheme.info.yml:

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

8.3 Casos de uso avanzados

Uso programático con #attached

Puedes adjuntar la librería GLightbox a cualquier render array:

// En preprocess o build()
$build['#attached']['library'][] = 'glightbox/glightbox';

$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Triggers personalizados en Twig

Para crear manualmente un trigger:

{# Imagen individual #}
<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>

{# Galería #}
{% 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 %}

Behavior personalizado de Drupal

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

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      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 Pruebas y aseguramiento de calidad

Después de completar la migración, revisa la siguiente lista de verificación antes de desplegar en producción:

Pruebas funcionales

• Las imágenes se abren en el lightbox en todos los tipos de contenido afectados
• La navegación de galería (flechas y teclado) funciona correctamente
• Los captions se muestran correctamente
• Los videos se reproducen automáticamente y se cierran correctamente
• El foco se restaura tras cerrar

Pruebas multibrowser

• Chrome, Edge, Firefox, Safari
• Verificar animaciones CSS

Pruebas móviles

• Gestos swipe funcionan
• Zoom táctil si está habilitado
• Overlay correcto en pantallas pequeñas

Accesibilidad

• Navegación con Tab correcta
• El foco vuelve al trigger
• Lectores de pantalla anuncian correctamente
• Sin errores críticos (axe/Lighthouse)

Rendimiento

• Reactivar agregación CSS/JS
• Comparar rendimiento con Colorbox
• Sin errores en consola

10 Problemas comunes y solución

Las imágenes no se abren

Síntoma: navega en vez de abrir lightbox.

• Verifica carga de librería GLightbox
• Comprueba agregación CSS/JS
• Revisa que exista class="glightbox"

Captions o galerías incorrectas

• Verifica data-description
• Comprueba configuración de captions
• Revisa IDs de galería

Conflictos JS

• Evita cargas duplicadas
• Comprueba window.GLightbox

Problemas de caché

• Ejecuta drush cr
• Verifica librerías en producción

drush @prod cr
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Conclusión

Migrar de Colorbox a GLightbox es un paso importante de modernización frontend:

• Eliminar dependencia de jQuery
• Mejor rendimiento
• Accesibilidad mejorada
• Alineación con Drupal moderno
• Menor mantenimiento

La migración es de bajo riesgo si se realiza de forma metódica. El módulo de Drupal simplifica el proceso mediante configuración declarativa.

Para proyectos en modernización frontend, este es un buen primer paso con impacto visible.