Drupal: substituir o Colorbox pelo GLightbox

1 Introdução

Os plugins de Lightbox são parte integrante dos sites baseados em Drupal há mais de uma década. Eles permitem que os editores exibam imagens, vídeos e outros materiais de mídia em um overlay pop-up sem sair da página atual — um padrão que os visitantes esperam em sites modernos com muita mídia.

Colorbox historicamente foi a solução principal no ecossistema Drupal. O módulo contribuído colorbox integra-se estreitamente aos formatadores de campos de imagem do Drupal, tem uma API madura e é amplamente conhecido pela comunidade. Porém, à medida que a web evoluiu, o Colorbox começou a mostrar sua idade: depende do jQuery, vem com um bundle mais pesado e ficou atrás das exigências modernas de acessibilidade.

Apresentamos o GLightbox — uma biblioteca de lightbox em JavaScript vanilla puro (sem dependências), com interface moderna, suporte robusto à acessibilidade e tamanho reduzido. O módulo Drupal correspondente integra-se facilmente aos mesmos campos de imagem e entidades de mídia com os quais o Colorbox trabalhava antes.

Este artigo vai conduzi-lo por todo o processo de migração: da auditoria da configuração atual do Colorbox à instalação do GLightbox, à reconfiguração dos formatadores de campo, à remoção segura do módulo antigo e ao ajuste fino da nova experiência do usuário para o seu tema.

2 Colorbox vs GLightbox: por que fazer a migração?

2.1 Limitações do Colorbox

O Colorbox foi criado em outra era da web. Sua arquitetura reflete premissas que já não fazem sentido no desenvolvimento Drupal moderno:

• Dependência do jQuery. O Colorbox é um plugin jQuery — não funciona sem ele. O núcleo do Drupal vem reduzindo gradualmente sua própria dependência do jQuery, e muitos temas focados em desempenho carregam o jQuery de forma adiada ou nem o utilizam.
• UI e animações datadas. Os estilos padrão do Colorbox parecem ultrapassados em comparação com as normas de design de 2024–2026. Para alcançar uma aparência moderna, muitas vezes é preciso uma customização de CSS considerável.
• Lacunas de acessibilidade. Embora o Colorbox tenha recebido algumas melhorias de acessibilidade ao longo dos anos, ele não foi projetado tendo o WCAG 2.1 AA como objetivo principal. A retenção de foco, os papéis ARIA e os anúncios para leitores de tela podem exigir trabalho adicional significativo.
• Ritmo de manutenção. A biblioteca jQuery Colorbox recebe atualizações com pouca frequência. Para um projeto Drupal de longo prazo, apostar em uma dependência de manutenção lenta cria riscos.

2.2 Vantagens do GLightbox

O GLightbox resolve diretamente cada um dos problemas listados:

• Sem dependências. JavaScript ES6+ puro; jQuery não é necessário.
• UX moderna. Transições CSS suaves, gestos de swipe, navegação por teclado e um tema padrão limpo que se integra bem a designs modernos.
• Acessibilidade completa. O foco é mantido dentro do lightbox, a navegação pelas setas do teclado funciona de imediato e a semântica ARIA correta role="dialog" é aplicada automaticamente.
• Peso leve. O pacote minificado e comprimido tem menos de 15 KB — cerca de 3 vezes mais leve do que uma configuração típica de Colorbox.
• Agrupamento de galerias. Suporte embutido a galerias agrupadas por meio do atributo data-gallery, sem necessidade de plugins adicionais.
• Desenvolvimento ativo. O projeto GLightbox no GitHub recebe regularmente novos releases e correções de bugs.

3 Visão geral do ecossistema Drupal

O núcleo do Drupal vem, há alguns anos, no caminho de reduzir o uso do jQuery, migrando para JS vanilla e APIs modernas de navegador. Isso se reflete na descontinuação de muitos mecanismos de comportamento baseados em jQuery no Drupal 10+ e no esforço dos temas para usar estratégias de JavaScript mais leves.

Do lado dos módulos contribuídos, tanto o Colorbox quanto o GLightbox têm seus próprios módulos Drupal no Drupal.org:

• colorbox — a escolha clássica, com integração profunda aos formatadores de campos de imagem, ao Views e ao sistema de mídia. Ainda é amplamente usado, porém recebe cada vez menos atualizações.
• glightbox — um módulo contribuído mais recente que encapsula a biblioteca GLightbox JS. Fornece formatadores de campo Image e Media, suporte a Views e um formulário de configurações para os parâmetros comuns do GLightbox.

4 Preparação para a migração

4.1 Auditoria do uso atual do Colorbox

Antes de alterar qualquer configuração, monte um panorama completo de onde e como o Colorbox é usado no seu site:

1. Campos de imagem. Vá em Structure → Content Types → [Type] → Manage display para cada tipo de conteúdo e verifique se algum campo de imagem usa o formatador Colorbox. Registre os estilos de imagem usados e as configurações de legenda.
2. Entidades de mídia. Verifique os modos de exibição dos tipos de mídia na seção Structure → Media types. Repita isso para cada tipo de mídia que inclua imagens ou vídeos.
3. Views. Encontre as views que incluem campos de imagem e verifique o formatador de campo usado. O Colorbox também pode ser aplicado por meio do plugin de formato "Colorbox" no Views.
4. Código personalizado. Pesquise nos módulos e temas personalizados por referências a colorbox, .colorbox, Drupal.behaviors.colorbox e à chave de biblioteca colorbox/colorbox.

# Busca rápida na base de código (execute a partir da raiz do Drupal)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Registre cada ocorrência encontrada. Na etapa de substituição, você precisará voltar a cada uma delas.

4.2 Backup e particularidades do ambiente

• Exporte a configuração ativa: drush config:export
• Faça commit da exportação no controle de versão antes de começar
• Desative a agregação de CSS/JS durante a migração (Admin → Performance)
• Crie um dump do banco de dados: drush sql:dump > pre-migration.sql
• Certifique-se de que o seu pipeline de deploy consegue levar as mudanças de configuração para staging/produção

``

5 Instalação e ativação do GLightbox no Drupal

5.1 Instalação da biblioteca JavaScript GLightbox

O módulo GLightbox do Drupal depende da biblioteca externa GLightbox JS. Há duas formas suportadas de incluí-la.

Opção A — Composer + Asset Packagist (recomendada)

# Adicionar o Asset Packagist como repositório (uma vez por projeto)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Incluir a biblioteca
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Adicione ou verifique a existência do caminho de instalação para npm-asset na seção extra.installer-paths do arquivo composer.json:

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

Após executar o comando composer install, a biblioteca será colocada no caminho web/libraries/glightbox/.

Opção B — Colocação manual

Baixe a versão mais recente na página de releases do GLightbox no GitHub e coloque os arquivos de modo que existam os seguintes caminhos:

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

5.2 Instalação e ativação do módulo Drupal GLightbox

# Baixar o módulo
composer require drupal/glightbox

# Ativar o módulo
drush en glightbox -y

# Limpar o cache
drush cr

Vá em Admin → Configuration → Media → GLightbox para confirmar que a biblioteca foi detectada e também para conhecer os parâmetros globais de configuração.

6 Substituição da funcionalidade do Colorbox

6.1 Campos de imagem

Este é o cenário de uso mais comum do Colorbox: um campo de imagem em um tipo de conteúdo, exibindo uma miniatura que abre a imagem em tamanho real em um lightbox.

1. Vá em Structure → Content Types → [Seu tipo] → Manage display.
2. Encontre o campo de imagem. Na lista suspensa Format, altere o valor de Colorbox para GLightbox.
3. Clique no ícone de configurações (⚙) para configurar o formatador. Defina o Image style (a miniatura exibida na página) e o Linked image style (a imagem carregada dentro do lightbox). Se necessário, ative as legendas.
4. Salve a configuração de exibição e limpe o cache: drush cr.

Você também pode exportar essa configuração e aplicá-la via YAML. Exemplo de configuração do formatador de campo no YAML de exibição do tipo de conteúdo:

# 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 Mídia e galerias

Para sites que usam o sistema de mídia do Drupal, os passos de migração são semelhantes, mas aplicam-se aos modos de exibição dos tipos de mídia.

• Vá em Structure → Media types → [Tipo] → Manage display.
• Troque o formatador do campo de origem da imagem de Colorbox para GLightbox.
• Para o agrupamento de galerias, configure o campo Gallery ID nos parâmetros do formatador GLightbox. Todos os itens com o mesmo Gallery ID poderão ser navegados como um grupo dentro do lightbox. Isso corresponde diretamente ao atributo nativo do GLightbox data-gallery.

O mapeamento das legendas é direto: o GLightbox usa o atributo data-description. O módulo Drupal permite mapeá-lo para o atributo title ou alt da imagem, ou para um valor de campo personalizado.

6.3 Integração com o Views

Se houver views que exibem imagens usando a formatação do Colorbox, atualize cada view da seguinte forma:

1. Abra a view em Structure → Views → [Nome da view] → Edit.
2. Na seção Fields, clique no campo de imagem. Na lista suspensa Formatter, troque de Colorbox para GLightbox.
3. Se a integração do Colorbox estava configurada no nível de Format (por exemplo, o plugin de formato "Colorbox"), mude para um formato padrão, como Unformatted list ou Grid, e aplique o formatador GLightbox no nível do campo.
4. Salve as alterações e limpe o cache.

7 Remoção segura do Colorbox

Depois que todos os formatadores e o código personalizado tiverem sido migrados, você pode remover o Colorbox com segurança. Siga os passos na ordem indicada para evitar erros de dependência:

1. Desinstale o módulo Colorbox. Desinstalá-lo antes de removê-lo permite que o Drupal faça a limpeza por meio do hook_uninstall().

   drush pm:uninstall colorbox -y

2. Remova-o do composer.json.

   composer remove drupal/colorbox

3. Remova a biblioteca JS do Colorbox de web/libraries/colorbox/, se ela tiver sido colocada manualmente.
4. Limpe o código personalizado. Encontre e remova todas as referências restantes às classes CSS do Colorbox (.colorbox, .colorbox-load), aos comportamentos JavaScript (Drupal.behaviors.colorbox) ou às inclusões de biblioteca (colorbox/colorbox).

5. Limpe todos os caches e exporte a configuração.

   drush cr
   drush config:export

8 Customização e melhorias

8.1 Parâmetros de configuração do GLightbox

A página de configurações globais do GLightbox (Admin → Configuration → Media → GLightbox) oferece os parâmetros usados com mais frequência. Eles correspondem diretamente à JavaScript API do GLightbox:

8.2 Tematização e estilização

O GLightbox vem com uma folha de estilos padrão (glightbox.min.css) que fornece um design de overlay escuro e limpo. Sobrescreva-a no seu tema sem alterar o arquivo da biblioteca:

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

/* Alterar o fundo do overlay */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

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

/* Aumentar as setas de navegação */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

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

Inclua o arquivo de sobrescrita de estilos no arquivo .libraries.yml do seu tema:

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

Depois, inclua-o globalmente no arquivo mytheme.info.yml:

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

8.3 Cenários de uso avançados

Inclusão programática via #attached

Você pode anexar a biblioteca GLightbox a qualquer render array em um módulo personalizado ou hook de preprocess:

// Em uma função de preprocess ou no build() de um bloco personalizado
$build['#attached']['library'][] = 'glightbox/glightbox';

// Passar parâmetros de configuração personalizados para as JS settings
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Triggers personalizados em templates Twig

Para criar manualmente um trigger do GLightbox em um template Twig, adicione os atributos correspondentes. O GLightbox reconhece qualquer elemento com class="glightbox" (ou o seletor que você configurar):

{# Abrir uma única imagem #}
<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>

{# Grupo de galeria — todos os itens com o mesmo data-gallery abrem juntos #}
{% 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 para inicialização personalizada

Se você precisa inicializar o GLightbox com parâmetros não disponíveis na interface administrativa do módulo, use um Drupal behavior personalizado:

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

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // A inicialização é executada apenas uma vez por contexto
      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 Testes e controle de qualidade

Depois de concluir a migração, execute a seguinte checklist de QA antes do deploy em produção:

Testes funcionais

• As imagens abrem no lightbox ao clicar em todos os tipos de conteúdo afetados
• A navegação da galeria (setas anterior/próximo, setas do teclado) funciona corretamente
• As legendas aparecem e correspondem ao valor esperado do campo
• Os vídeos (YouTube, Vimeo, locais) reproduzem automaticamente e fecham corretamente
• O fechamento do lightbox (botão ✕, tecla Escape, clique fora da área) restaura o foco

Testes cross-browser

• Chrome/Edge (Chromium), Firefox, Safari (macOS e iOS)
• Certifique-se de que as animações CSS aparecem corretamente em todos os navegadores testados

Testes em dispositivos móveis

• Swipe para a esquerda/direita para navegar pelos itens da galeria
• Pinch-to-zoom nas imagens (se ativado)
• O overlay cobre corretamente a área de visualização em telas pequenas

Verificações de acessibilidade

• A tecla Tab percorre ciclicamente os controles do lightbox (fechar, anterior, próximo)
• Após o fechamento, o foco retorna ao elemento que acionou o lightbox
• O leitor de tela anuncia o diálogo e seu conteúdo (verifique com NVDA ou VoiceOver)
• Execute uma auditoria de acessibilidade com axe DevTools ou Lighthouse — meta: nenhum erro crítico

Desempenho

• Reative a agregação de CSS/JS e confirme que o GLightbox ainda é inicializado
• Execute uma auditoria de desempenho no Lighthouse e compare com a versão de referência do Colorbox
• Confirme a ausência de erros de JavaScript no console em todas as páginas testadas

10 Problemas comuns e suas soluções

As imagens não abrem no Lightbox

Sintoma: Ao clicar na imagem, ocorre a navegação pelo link em vez da abertura do GLightbox.

• Verifique se a biblioteca GLightbox está sendo carregada: abra o DevTools do navegador → aba Network e filtre por glightbox.
• Certifique-se de que a agregação de CSS/JS funciona corretamente; tente desativá-la temporariamente para identificar problemas de agregação.
• Verifique o HTML gerado e confirme que o elemento de trigger contém o atributo class="glightbox".

Ausência de legendas ou funcionamento incorreto das galerias

Sintoma: As legendas estão vazias ou a navegação da galeria pula itens.

• Verifique as tags anchor geradas: confirme que data-description está preenchido e que os valores de data-gallery coincidem nos itens agrupados.
• Verifique se o parâmetro do formatador Caption source aponta para um campo não vazio.
• Para o agrupamento de galerias, confirme que o ID da galeria está definido corretamente.

Conflitos com outras bibliotecas JS

Sintoma: O GLightbox inicializa parcialmente ou gera erros no console.

• Verifique inclusões duplicadas da biblioteca GLightbox (módulo + inclusão manual no tema).
• Verifique se nenhuma outra biblioteca sobrescreve window.GLightbox.
• Se o seu tema usa um bundler de JS, confirme que o GLightbox não está sendo empacotado separadamente.

Problemas de cache e agregação

Sintoma: O GLightbox funciona em desenvolvimento, mas para de funcionar em produção.

• Execute drush cr em produção após o deploy das mudanças de configuração.
• Confirme que web/libraries/glightbox/ foi commitado e implantado corretamente.
• Se a agregação de CSS altera a especificidade dos seletores do GLightbox — inclua o arquivo de sobrescritas mais tarde.

# Limpar todos os caches em produção (se o Drush estiver disponível)
drush @prod cr

# Verificar a existência do arquivo da biblioteca
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Conclusão

A migração do Colorbox para o GLightbox é um passo importante de modernização do frontend de qualquer projeto Drupal. As vantagens são evidentes:

• Eliminação da dependência do lightbox em relação ao jQuery
• Experiência de usuário mais rápida e mais leve
• Conformidade com os requisitos de acessibilidade «de fábrica», sem patches adicionais
• Alinhamento com a direção de evolução do Drupal rumo ao JavaScript vanilla
• Redução da carga de manutenção de longo prazo graças a uma biblioteca de desenvolvimento ativo

A própria migração é de baixo risco com uma abordagem sistemática: primeiro a auditoria, depois a migração gradual dos formatadores de campo, a limpeza do código obsoleto e testes minuciosos antes do deploy. O módulo Drupal glightbox torna grande parte do processo declarativa — as mudanças são feitas pela interface administrativa, e não por código personalizado.

Para sites que passam por uma modernização mais ampla do frontend — migração para arquitetura decoupled ou headless, adoção de um tema moderno (Olivero, Gin ou um design system próprio) ou redução do peso de JavaScript — substituir o Colorbox pelo GLightbox é um excelente ponto de partida, com efeito notável e risco mínimo.