Drupal: Заменить Colorbox на GLightbox

1 Введение

Плагины Lightbox уже более десяти лет являются неотъемлемой частью веб‑сайтов на базе Drupal. Они позволяют редакторам отображать изображения, видео и другие медиа‑материалы во всплывающем оверлее без перехода с текущей страницы — шаблон, которого посетители ожидают на современных сайтах с большим количеством мультимедиа.

Colorbox исторически был основным решением в экосистеме Drupal. Контрибутивный модуль colorbox тесно интегрируется с форматтерами полей изображений Drupal, обладает зрелым API и широко известен сообществу. Однако по мере развития веба Colorbox начал демонстрировать свой возраст: он зависит от jQuery, поставляется с более тяжёлым бандлом и отстаёт от современных требований к доступности.

Представляем GLightbox — библиотеку lightbox на чистом vanilla‑JavaScript (без зависимостей) с современным пользовательским интерфейсом, надёжной поддержкой доступности и небольшим размером. Соответствующий модуль Drupal легко интегрируется с теми же полями изображений и медиа‑сущностями, с которыми ранее работал Colorbox.

Эта статья проведёт вас через полный процесс миграции: от аудита текущей конфигурации Colorbox до установки GLightbox, перенастройки форматтеров полей, безопасного удаления старого модуля и тонкой настройки нового пользовательского опыта для вашей темы.

2 Colorbox vs GLightbox: Почему стоит выполнить миграцию?

2.1 Ограничения Colorbox

Colorbox был создан в другую эпоху веба. Его архитектура отражает предположения, которые больше не актуальны в современной разработке на Drupal:

• Зависимость от jQuery. Colorbox — это плагин jQuery — он не может работать без него. Ядро Drupal постепенно сокращает собственную зависимость от jQuery, а многие темы, ориентированные на производительность, загружают jQuery отложенно или вовсе не используют его.
• Устаревший UI и анимации. Стандартные стили Colorbox выглядят устаревшими по сравнению с дизайнерскими нормами 2024–2026 годов. Для достижения современного внешнего вида часто требуется серьёзная кастомизация CSS.
• Пробелы в доступности. Хотя Colorbox получал некоторые улучшения доступности на протяжении лет, он не проектировался с учётом WCAG 2.1 AA как основной цели. Удержание фокуса, ARIA‑роли и уведомления для скринридеров могут требовать значительной дополнительной работы.
• Темп сопровождения. Библиотека jQuery Colorbox получает обновления нечасто. Для долгосрочного Drupal‑проекта ставка на медленно сопровождаемую зависимость создаёт риски.

2.2 Преимущества GLightbox

GLightbox напрямую решает каждую из перечисленных проблем:

• Без зависимостей. Чистый ES6+ JavaScript; jQuery не требуется.
• Современный UX. Плавные CSS‑переходы, жесты свайпа, навигация с клавиатуры и чистая тема по умолчанию, хорошо интегрирующаяся в современные дизайны.
• Полноценная доступность. Фокус удерживается внутри lightbox, навигация стрелками клавиатуры работает из коробки, а корректная ARIA‑семантика role="dialog" применяется автоматически.
• Лёгкий вес. Минифицированный и сжатый пакет составляет менее 15 KB — примерно в 3 раза легче типичной конфигурации Colorbox.
• Группировка галерей. Встроенная поддержка группированных галерей через атрибут data-gallery, без необходимости использования дополнительных плагинов.
• Активная разработка. Проект GLightbox на GitHub регулярно получает новые релизы и исправления ошибок.

3 Обзор экосистемы Drupal

Ядро Drupal уже несколько лет движется по пути сокращения использования jQuery, переходя к vanilla JS и современным API браузеров. Это отражено в устаревании многих поведенческих механизмов, основанных на jQuery, в Drupal 10+ и в стремлении тем использовать более лёгкие стратегии JavaScript.

Со стороны контрибутивных модулей как Colorbox, так и GLightbox имеют собственные модули Drupal на Drupal.org:

• colorbox — классический выбор с глубокой интеграцией в форматтеры полей изображений, Views и медиасистему. По‑прежнему широко используется, однако получает всё меньше обновлений.
• glightbox — более новый контрибутивный модуль, оборачивающий библиотеку GLightbox JS. Предоставляет форматтеры полей Image и Media, поддержку Views и форму настроек для распространённых параметров GLightbox.

4 Подготовка к миграции

4.1 Аудит текущего использования Colorbox

Перед изменением любой конфигурации составьте полную картину того, где и как Colorbox используется на вашем сайте:

1. Поля изображений. Перейдите в Structure → Content Types → [Type] → Manage display для каждого типа контента и проверьте, использует ли какое‑либо поле изображения форматтер Colorbox. Зафиксируйте используемые стили изображений и настройки подписей.
2. Медиа‑сущности. Проверьте режимы отображения типов медиа в разделе Structure → Media types. Повторите это для каждого типа медиа, включающего изображения или видео.
3. Views. Найдите представления (Views), которые включают поля изображений, и проверьте используемый форматтер поля. Colorbox также может применяться через плагин формата "Colorbox" в Views.
4. Пользовательский код. Выполните поиск в пользовательских модулях и темах по ссылкам на colorbox, .colorbox, Drupal.behaviors.colorbox и ключ библиотеки colorbox/colorbox.

# Быстрый поиск по кодовой базе (запустите из корня Drupal)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Зафиксируйте каждое найденное место. На этапе замены вам потребуется вернуться к каждому из них.

4.2 Резервное копирование и особенности окружения

• Экспортируйте активную конфигурацию: drush config:export
• Закоммитьте экспорт в систему контроля версий перед началом
• Отключите агрегацию CSS/JS во время миграции (Admin → Performance)
• Создайте дамп базы данных: drush sql:dump > pre-migration.sql
• Убедитесь, что ваш pipeline деплоя может передавать изменения конфигурации на staging/production

``

5 Установка и включение GLightbox в Drupal

5.1 Установка JavaScript‑библиотеки GLightbox

Drupal‑модуль GLightbox зависит от внешней библиотеки GLightbox JS. Существует два поддерживаемых способа её подключения.

Вариант A — Composer + Asset Packagist (рекомендуется)

# Добавить Asset Packagist как репозиторий (один раз для проекта)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Подключить библиотеку
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Добавьте или убедитесь в наличии пути установки для npm-asset в разделе extra.installer-paths файла composer.json:

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

После выполнения команды composer install библиотека будет размещена по пути web/libraries/glightbox/.

Вариант B — Ручное размещение

Скачайте последнюю версию со страницы релизов GLightbox в GitHub и разместите файлы так, чтобы существовали следующие пути:

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

5.2 Установка и включение Drupal‑модуля GLightbox

# Загрузить модуль
composer require drupal/glightbox

# Включить модуль
drush en glightbox -y

# Очистить кеш
drush cr

Перейдите в раздел Admin → Configuration → Media → GLightbox, чтобы убедиться, что библиотека обнаружена, а также ознакомиться с глобальными параметрами конфигурации.

6 Замена функциональности Colorbox

6.1 Поля изображений

Это наиболее распространённый сценарий использования Colorbox: поле изображения в типе контента, отображающее миниатюру, которая открывает полноразмерное изображение в lightbox.

1. Перейдите в раздел Structure → Content Types → [Ваш тип] → Manage display.
2. Найдите поле изображения. В раскрывающемся списке Format измените значение с Colorbox на GLightbox.
3. Нажмите на значок настроек (⚙), чтобы настроить форматтер. Установите Image style (миниатюра, отображаемая на странице) и Linked image style (изображение, загружаемое внутри lightbox). При необходимости включите подписи.
4. Сохраните конфигурацию отображения и очистите кеш: drush cr.

Вы также можете экспортировать эту конфигурацию и применить её через YAML. Пример конфигурации форматтера поля в YAML отображения типа контента:

# core.entity_view_display.node.article.default.yml (фрагмент)
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 Медиа и галереи

Для сайтов, использующих медиасистему Drupal, шаги миграции аналогичны, но применяются к режимам отображения типов медиа.

• Перейдите в раздел Structure → Media types → [Тип] → Manage display.
• Переключите форматтер поля источника изображения с Colorbox на GLightbox.
• Для группировки галерей настройте поле Gallery ID в параметрах форматтера GLightbox. Все элементы с одинаковым Gallery ID будут доступны для навигации как группа внутри lightbox. Это напрямую сопоставляется с нативным атрибутом GLightbox data-gallery.

Сопоставление подписей выполняется напрямую: GLightbox использует атрибут data-description. Drupal‑модуль позволяет сопоставить его с атрибутом title или alt изображения, либо с пользовательским значением поля.

6.3 Интеграция с Views

Если Views отображают изображения с использованием форматирования Colorbox, обновите каждое представление следующим образом:

1. Откройте представление в разделе Structure → Views → [Имя представления] → Edit.
2. В разделе Fields нажмите на поле изображения. В раскрывающемся списке Formatter переключитесь с Colorbox на GLightbox.
3. Если интеграция Colorbox была настроена на уровне Format (например, плагин формата "Colorbox"), переключитесь на стандартный формат, такой как Unformatted list или Grid, и примените форматтер GLightbox на уровне поля.
4. Сохраните изменения и очистите кеш.

7 Безопасное удаление Colorbox

После того как все форматтеры и пользовательский код были перенесены, вы можете безопасно удалить Colorbox. Выполните следующие шаги в указанном порядке, чтобы избежать ошибок зависимостей:

1. Отключите модуль Colorbox. Отключение перед удалением позволяет Drupal выполнить очистку через hook_uninstall().

   drush pm:uninstall colorbox -y

2. Удалите его из composer.json.

   composer remove drupal/colorbox

3. Удалите JS‑библиотеку Colorbox из web/libraries/colorbox/, если она была размещена вручную.
4. Очистите пользовательский код. Найдите и удалите все оставшиеся ссылки на CSS‑классы Colorbox (.colorbox, .colorbox-load), JavaScript‑поведения (Drupal.behaviors.colorbox) или подключения библиотек (colorbox/colorbox).

5. Очистите все кеши и экспортируйте конфигурацию.

   drush cr
   drush config:export

8 Кастомизация и улучшения

8.1 Параметры конфигурации GLightbox

Страница глобальных настроек GLightbox (Admin → Configuration → Media → GLightbox) предоставляет наиболее часто используемые параметры. Они напрямую соответствуют JavaScript API GLightbox:

8.2 Темизация и стилизация

GLightbox поставляется со стандартной таблицей стилей (glightbox.min.css), обеспечивающей чистый тёмный overlay‑дизайн. Переопределяйте её в своей теме без изменения файла библиотеки:

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

/* Изменение фона overlay */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* Стилизация области подписи */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* Увеличение стрелок навигации */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* Вариант для светлой темы */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

Подключите файл переопределения стилей в файле .libraries.yml вашей темы:

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

Затем подключите его глобально в файле mytheme.info.yml:

# mytheme.info.yml (фрагмент)
libraries:
  - mytheme/glightbox-overrides

8.3 Расширенные сценарии использования

Программное подключение через #attached

Вы можете подключить библиотеку GLightbox к любому render array в пользовательском модуле или preprocess‑хуке:

// В preprocess‑функции или build() пользовательского блока
$build['#attached']['library'][] = 'glightbox/glightbox';

// Передать пользовательские параметры конфигурации в JS settings
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Пользовательские триггеры в Twig‑шаблонах

Чтобы вручную создать триггер GLightbox в Twig‑шаблоне, добавьте соответствующие атрибуты. GLightbox распознаёт любой элемент с class="glightbox" (или селектором, который вы настроили):

{# Открыть одно изображение #}
<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>

{# Группа галереи — все элементы с одинаковым data-gallery откроются вместе #}
{% 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 для пользовательской инициализации

Если вам необходимо инициализировать GLightbox с параметрами, не доступными в административном интерфейсе модуля, используйте пользовательское поведение 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 Тестирование и контроль качества

После завершения миграции выполните следующий контрольный список QA перед развертыванием в production:

Функциональное тестирование

• Изображения открываются в lightbox при клике во всех затронутых типах контента
• Навигация галереи (стрелки назад/вперёд, клавиши со стрелками на клавиатуре) работает корректно
• Подписи отображаются и соответствуют ожидаемому значению поля
• Видео (YouTube, Vimeo, локальные) автоматически воспроизводятся и корректно закрываются
• Закрытие lightbox (кнопка ✕, клавиша Escape, клик вне области) восстанавливает фокус

Кросс‑браузерное тестирование

• Chrome/Edge (Chromium), Firefox, Safari (macOS и iOS)
• Убедитесь, что CSS‑анимации корректно отображаются во всех протестированных браузерах

Тестирование на мобильных устройствах

• Свайп влево/вправо для навигации по элементам галереи
• Pinch‑to‑zoom на изображениях (если включено)
• Overlay корректно покрывает область просмотра на небольших экранах

Проверки доступности

• Клавиша Tab циклически перемещается между элементами управления lightbox (закрыть, предыдущий, следующий)
• После закрытия фокус возвращается к элементу‑триггеру
• Скринридер объявляет диалог и его содержимое (проверить с NVDA или VoiceOver)
• Запустите аудит доступности axe DevTools или Lighthouse — целевой показатель: отсутствие критических ошибок

Производительность

• Повторно включите агрегацию CSS/JS и убедитесь, что GLightbox всё ещё инициализируется
• Запустите аудит производительности Lighthouse и сравните с базовой версией Colorbox
• Убедитесь в отсутствии ошибок JavaScript в консоли на всех протестированных страницах

10 Распространённые проблемы и их решение

Изображения не открываются в Lightbox

Симптом: При клике на изображение выполняется переход по ссылке вместо открытия GLightbox.

• Проверьте, что библиотека GLightbox загружается: откройте DevTools браузера → вкладка Network и отфильтруйте по glightbox.
• Убедитесь, что агрегация CSS/JS работает корректно; попробуйте временно отключить её для выявления проблем агрегации.
• Проверьте сгенерированный HTML и убедитесь, что элемент‑триггер содержит атрибут class="glightbox".

Отсутствие подписей или некорректная работа галерей

Симптом: Подписи пусты или навигация по галерее пропускает элементы.

• Проверьте сгенерированные anchor‑теги: убедитесь, что data-description заполнен, а значения data-gallery совпадают у сгруппированных элементов.
• Проверьте, что параметр форматтера Caption source указывает на непустое поле.
• Для группировки галерей убедитесь, что ID галереи задан корректно.

Конфликты с другими JS‑библиотеками

Симптом: GLightbox частично инициализируется или выдаёт ошибки в консоли.

• Проверьте дублирующиеся подключения библиотеки GLightbox (модуль + ручное подключение в теме).
• Проверьте, что ни одна другая библиотека не переопределяет window.GLightbox.
• Если ваша тема использует JS‑bundler, убедитесь, что GLightbox не бандлится отдельно.

Проблемы кеша и агрегации

Симптом: GLightbox работает в development, но перестаёт работать в production.

• Выполните drush cr в production после деплоя конфигурационных изменений.
• Убедитесь, что web/libraries/glightbox/ закоммичен и корректно задеплоен.
• Если агрегация CSS изменяет специфичность селекторов GLightbox — подключите файл переопределений позднее.

# Очистка всех кешей в production (если доступен Drush)
drush @prod cr

# Проверка наличия файла библиотеки
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Заключение

Миграция с Colorbox на GLightbox — важный шаг модернизации frontend‑части любого Drupal‑проекта. Преимущества очевидны:

• Устранение зависимости lightbox от jQuery
• Более быстрый и лёгкий пользовательский опыт
• Соответствие требованиям доступности «из коробки» без дополнительных патчей
• Соответствие направлению развития Drupal в сторону vanilla JavaScript
• Снижение долгосрочной нагрузки на сопровождение благодаря активно развиваемой библиотеке

Сама миграция имеет низкий риск при системном подходе: сначала аудит, затем поэтапный перенос форматтеров полей, очистка устаревшего кода и тщательное тестирование перед деплоем. Drupal‑модуль glightbox делает большую часть процесса декларативной — изменения выполняются через интерфейс администратора, а не через пользовательский код.

Для сайтов, проводящих более широкую модернизацию frontend‑части — переход к decoupled или headless‑архитектуре, внедрение современной темы (Olivero, Gin или собственной дизайн‑системы) или сокращение веса JavaScript — замена Colorbox на GLightbox является отличной начальной точкой с заметным эффектом при минимальном риске.