LightGallery Formatter превращает медиаполе Drupal в аккуратную галерею, которая удобна и на сенсорных экранах. Модуль использует JavaScript библиотеку lightGallery. Вы один раз настраиваете стиль галереи и потом применяете его к любому полю.

Модуль создали и поддерживают Andrii и Denys.

Что это такое

LightGallery Formatter это форматтер поля для полей со ссылкой на Media. Выберите его в разделе Manage display, укажите профиль, и ваши изображения, удалённые видео (YouTube и Vimeo) и PDF файлы будут открываться во всплывающем окне просмотра.

Писать JSON или код не нужно. Все настройки сделаны в виде флажков и выпадающих списков в панели администратора.

Форматтер появляется у поля со ссылкой на Media, если поле может хранить тип Media с изображениями или стандартный тип Document (файловый тип с машинным именем document). Он также появляется, если для поля не ограничены типы Media. Если поле разрешает только удалённое видео, форматтер не предлагается.

Зачем он нужен

Существующий модуль drupal/lightgallery требует настраивать каждое поле отдельно. Когда на сайте много галерей, это отнимает много времени.

Наш модуль вместо этого использует повторно применяемые профили. Создайте столько профилей, сколько нужно. Измените один профиль, и все галереи с этим профилем изменятся вместе с ним. Вы настраиваете один раз и используете везде.

Библиотеку также не нужно подключать вручную. lightGallery 2.9.0 уже входит в модуль вместе с React. Не нужно ничего скачивать отдельно и не нужно настраивать свои пути в Composer.

Основные возможности

• Повторно используемые профили. Один профиль может работать для многих полей.
• Разные типы медиа в одной галерее. Изображения, видео YouTube, видео Vimeo и PDF файлы, в том порядке, который задал редактор.
• Библиотека уже внутри. lightGallery и React входят в модуль. Не нужно скачивать JavaScript вручную и не нужно подключать библиотеку через Composer.
• 31 вариант перехода. Slide, Fade, Zoom, Lollipop, Rotate, Tube и другие, все в одном выпадающем списке.
• Богатое управление. Масштаб, полный экран, миниатюры, кнопка скачивания и управление с клавиатуры клавишами Esc и стрелками. Колесо мыши включается по желанию.
• Поддержка касаний. Свайп и перетаскивание на телефонах и планшетах. Любой из этих способов можно отключить.
• Автоматическое скрытие кнопок. По желанию, с задержкой, которую вы задаёте сами.
• Миниатюры видео. Миниатюры YouTube и Vimeo берутся из миниатюры элемента Media.
• Клонирование профилей. Скопируйте профиль и используйте его как основу для нового. Новое в версии 1.1.0.
• PDF в галерее. PDF файлы открываются в окне просмотра через встроенный просмотрщик браузера. Новое в версии 1.1.0.
• Экспорт конфигурации. Профили переносятся между сайтами обычными средствами конфигурации Drupal.
• Предпросмотр. Проверяйте профиль прямо во время редактирования. Для этого нужен необязательный подмодуль.
• Обычные ссылки как запасной вариант. Ссылки на изображения и PDF работают до загрузки скрипта и в случае, если скрипт не загрузился.
• Запись в отчёте о состоянии. Отчёт о состоянии Drupal показывает версию встроенной lightGallery.

Требования

• Drupal ^10.3, ^11 или ^12
• Модули ядра Media и Media Library. Модулю нужны оба.
• Для PDF файлов нужен стандартный тип Media Document и хотя бы один тип Media с изображениями для миниатюры PDF

Установка

Установите модуль через Composer. Node.js и npm на вашем сайте не нужны. JavaScript уже собран и лежит внутри модуля.

composer require drupal/lightgallery_formatter

Включите модуль через Drush.

drush en lightgallery_formatter

Необязательные подмодули можно включить так же.

drush en lightgallery_formatter_preview lightgallery_formatter_demo

Если вам удобнее админ панель, откройте раздел Extend, найдите группу LightGallery и отметьте нужные модули.

Быстрый старт

Шаг 1. Создайте профиль

1. Откройте Configuration → Media → LightGallery (/admin/config/media/lightgallery).
2. Нажмите Add LightGallery profile.
3. Введите Label и Machine name. Машинное имя можно менять только пока профиль новый.
4. Задайте общие настройки. Смотрите раздел «Профили и настройки» ниже.
5. Включите нужные плагины, например миниатюры, масштаб или полный экран.
6. Если включён подмодуль Preview, нажмите Generate Preview в верхней части формы, чтобы проверить настройки.
7. Сохраните профиль.

В модуле есть один готовый профиль с названием Default. Для управления профилями нужно право Administer LightGallery formatter.

Шаг 2. Примените профиль к медиаполю

1. Откройте Structure → Content types → (ваш тип) → Manage display.
2. Найдите своё поле со ссылкой на Media.
3. Выберите форматтер LightGallery.
4. Нажмите на значок шестерёнки.
5. Выберите LightGallery Profile. В списке показаны только включённые профили.
6. Выберите стиль изображения для Gallery thumbnails (inline on page).
7. Если в поле лежат PDF файлы, выберите миниатюру для PDF. Смотрите раздел «Работа с PDF» ниже.
8. Сохраните.

Проверьте также, что поле разрешает нужные типы Media. Отметьте Image для картинок, Remote video для YouTube и Vimeo и Document для PDF файлов.

Шаг 3. Проверьте результат

Откройте материал с изображениями, видео или PDF файлами. Они покажутся как одна галерея, в том же порядке, который задал редактор.

Профили и настройки

Профиль это сущность конфигурации Drupal (lightgallery_profile). В ней хранятся название, машинное имя, флажок Enabled и настройки каждого плагина. В настройках форматтера поля можно выбрать только включённые профили.

Клонирование профиля (новое в 1.1.0)

Клонирование помогает быстро сделать вариант профиля, который вам уже нравится.

1. Откройте Configuration → Media → LightGallery (/admin/config/media/lightgallery).
2. В колонке Operations рядом с нужным профилем откройте выпадающий список и выберите Clone.
3. Форма клонирования открывается по адресу /admin/config/media/lightgallery/{machine_name}/clone. Это та же форма, что и для добавления и редактирования, уже заполненная настройками исходного профиля.
4. В поле Label стоит название исходного профиля с добавлением (copy). Измените его.
5. Поле Machine name пустое. Введите новое имя из строчных букв, цифр и символов подчёркивания. Уже занятое имя будет отклонено.
6. Измените любые настройки и нажмите Save.

Что полезно знать

• Пока вы не нажмёте Save, ничего не сохраняется. Если вы уйдёте со страницы, клон не будет создан.
• Флажок Enabled и настройки всех плагинов копируются. Это относится к General, Thumbnail, Zoom, Video и остальным, вместе с их состоянием включено или выключено.
• Исходный профиль не меняется.
• Клон это новый отдельный профиль. Если вы позже измените его, оригинал не пострадает, и наоборот.
• После сохранения вы вернётесь к списку профилей с сообщением «Created the ... LightGallery profile.»
• Для клонирования нужно то же право, что и для редактирования, то есть Administer LightGallery formatter.

Общие настройки

Эти настройки включены всегда. Они находятся в разделе General Settings формы.

• License key. Смотрите раздел «О ключе лицензии» ниже.
• Enable looping. После последнего слайда снова показывается первый.
• Preload count. Сколько слайдов загружать заранее, от 1 до 5.
• Transition speed (ms). Скорость анимации в миллисекундах.
• Transition mode. Стиль перехода. Доступно 31 вариант.
• Closable, Close on tap и Close with Esc key. Они определяют, как посетитель может закрыть окно просмотра.
• Keyboard navigation. Стрелки и похожие клавиши.
• Show close icon и Show maximize icon.
• Hide controls delay (ms). Скрывает панель кнопок после этой задержки. Значение 0 оставляет панель на виду.
• Show counter. Показывает номер слайда и общее число слайдов.
• Enable download. Показывает кнопку скачивания.
• Enable desktop drag и Enable touch swipe.
• Mouse wheel navigation.
• Allow media overlap. Оставьте включённым, если хотите видеть на панели переключатель миниатюр и значки других плагинов.

В готовом профиле Default, который идёт с модулем, кнопка скачивания выключена. В новом профиле она включена с самого начала.

Плагины

В коде есть 12 плагинов. Плагин General включён всегда. Остальные 11 вы включаете по одному внутри профиля. В README указано 11, потому что там не учтён плагин Video.

• General. Основные параметры, описанные выше. Всегда включён.
• Video. Позволяет проигрывать видео в окне просмотра, для YouTube и Vimeo. Настройки включают автозапуск первого видео, автозапуск при смене слайда, переход к следующему слайду после окончания видео и параметр Video.js.
• Thumbnail Navigation. Полоса миниатюр внизу окна просмотра. Настройки включают стиль изображения, ширину, высоту, отступ, положение текущей миниатюры, выравнивание, кнопку переключения и место для неё.
• Zoom. Увеличение и уменьшение, а также показ в реальном размере. Настройки включают масштаб, бесконечное увеличение, кнопку реального размера, значки масштаба и задержку перед включением масштаба.
• Fullscreen. Открывает галерею на всё окно браузера. Настроек нет.
• Pager. Индикатор номера страницы.
• Relative Caption. Подписи рядом с изображением.
• Rotate. Поворот и отражение изображений. Настройки включают скорость поворота, поворот влево и вправо, отражение по горизонтали и по вертикали.
• Autoplay. Автоматический показ слайдов. Настройки включают автостарт, интервал (по умолчанию 5000 мс), полосу прогресса, принудительный автозапуск, а также кнопки управления и их место.
• Medium Zoom. Увеличение в стиле Medium. Настройки включают отступ и цвет фона.
• Share. Кнопки для публикации в соцсетях Facebook, Twitter и Pinterest. Каждую можно включить или выключить, а также изменить текст кнопки.
• Hash. Прямые ссылки на отдельный слайд в адресе страницы. Настройки включают включение hash и собственные названия слайдов.

У каждого плагина, кроме General, есть свой флажок Enable ... plugin. В новом профиле в браузер отправляются только отмеченные плагины.

Два вида миниатюр

• Миниатюры галереи это сетка на странице. Стиль изображения выбирается в форматтере поля.
• Миниатюры окна просмотра это полоса внутри окна просмотра. Стиль изображения выбирается в профиле, в разделе Thumbnail Navigation. Если оставить его пустым, полоса использует стиль миниатюр галереи из поля.

Прямые ссылки (плагин Hash)

Когда плагин Hash включён, адрес страницы меняется по мере перехода по галерее. Формат такой #lg={gallery-id}&slide={index}. Номер слайда начинается с 0. Если включён параметр Custom slide name, то вместо номера используется название слайда, если оно есть.

Если на одной странице несколько галерей с включённым плагином Hash, проверьте прямые ссылки, прежде чем на них полагаться.

Известные особенности плагинов

• Hash вместе с Thumbnail Navigation в некоторых браузерах может работать странно.
• Relative Caption может записывать предупреждение в консоль браузера во время переходов. На работу галереи это не влияет.
• Нажатия Medium Zoom могут конфликтовать с нажатиями на полосу миниатюр.

Если вы заметили проблему, отключите один из плагинов в профиле.

О ключе лицензии

Встроенная lightGallery 2.9.0 это программа с открытым кодом под лицензией GPLv3. Файл package.json библиотеки и заголовок лицензии во встроенном файле указывают GPLv3.

В форме профиля есть поле License key. В нём стоит значение 0000-0000-000-0000, а подсказка в форме предлагает использовать его для некоммерческих проектов. Модуль ключ не проверяет. Он передаёт значение в lightGallery, а библиотека только пишет сообщение в консоль браузера. Если ключ стандартный, библиотека пишет предупреждение, что ключ не подходит для рабочего сайта. Если поле пустое, она пишет ошибку с просьбой указать действующий ключ. В обоих случаях галерея работает.

Коммерческая лицензия нужна проектам, которые держат свой исходный код закрытым. На странице лицензии lightGallery сказано, что GPLv3 бесплатна, а платная лицензия предназначена для проектов с закрытым кодом. Модули Drupal распространяются под GPL, поэтому для большинства сайтов на Drupal подходит вариант GPLv3. Если вы не уверены насчёт своего проекта, прочитайте условия на https://www.lightgalleryjs.com/license/ или спросите авторов библиотеки.

Поддерживаемые типы медиа

• Изображения. Стандартные элементы Media с изображениями. Для миниатюр используйте стили изображений Drupal. В настройках форматтера, в разделе Gallery item source by media type, можно выбрать поле с изображением для каждого типа Media.
• YouTube и Vimeo. Элементы удалённого видео, с миниатюрами из миниатюры элемента Media. Форматтер считает удалённым видео типы Media с машинными именами remote_video, video или oembed_video. Включите в профиле плагин Video, чтобы видео проигрывалось в окне просмотра.
• PDF файлы. Стандартный тип Media Document с машинным именем document и файловым источником. Новое в версии 1.1.0.
• Файлы видео HTML5. Форматтер поля их не поддерживает. Смотрите раздел «О видео» ниже.

Работа с PDF

Как показывается PDF

• PDF открывается внутри окна просмотра как слайд с iframe, который использует встроенный просмотрщик PDF в браузере. У модуля нет собственного просмотрщика PDF. В коде нет pdf.js и нет тегов embed или object.
• Изображения и PDF файлы могут лежать в одном поле. Порядок, заданный редактором, сохраняется для кнопок «назад» и «вперёд».
• У каждого слайда с PDF есть подпись с именем файла и ссылка Open or download PDF, которая открывает исходный файл в новой вкладке.

Что считается PDF

• Элемент Media должен быть типа document с файловым источником.
• MIME тип сохранённого файла должен быть точно application/pdf. Одного расширения .pdf в имени файла недостаточно.
• В коде нет ограничений на размер файла и на число PDF файлов в галерее.

Миниатюра для PDF

• У PDF нет собственной картинки, поэтому вы выбираете для него одно изображение. Это настройка отображения поля, а не профиля.
• В настройках форматтера (значок шестерёнки) откройте Gallery item source by media type и найдите PDF settings. Если у поля не ограничены типы Media, PDF settings показывается отдельно.
• Нажмите Select PDF thumbnail. Откроется обычная Media Library Drupal во всплывающем окне. Можно выбрать ровно один элемент. Предлагаются только типы Media с изображениями.
• После выбора в сводке появится надпись «Selected thumbnail», а кнопка станет Change PDF thumbnail.
• Выбранное изображение должно быть опубликовано и доступно пользователю. Оно общее для всех PDF файлов в этом отображении поля. Его используют и для сетки на странице, и для полосы в окне просмотра, каждый раз со своим стилем изображения.
• Если миниатюра не выбрана, или выбранная снята с публикации, скрыта или удалена, PDF файлы в этой галерее пропускаются. Изображения при этом показываются.
• Если на сайте нет типа Media с изображениями, выбор не показывается, а настройка сохраняется как 0.
• Строка сводки под форматтером показывает «PDF thumbnail: not configured», пока вы не сделаете выбор.

Если что-то нельзя показать

• Элемент Media, который нельзя показать, пропускается, а галерея продолжает работать. В журнал lightgallery_formatter записывается одно короткое предупреждение. Причиной может быть отсутствие поля источника, отсутствие файла, неверный MIME тип, неподдерживаемый тип Media или отсутствие миниатюры для PDF.
• Если пропущены все элементы, для этого поля ничего не показывается.

Если браузер не может показать PDF прямо в окне

• Скрипт проверяет, включён ли в браузере просмотрщик PDF. Если нет, PDF файлы не открываются в окне просмотра. Миниатюра становится обычной ссылкой на PDF, а под ней появляется ссылка Open or download PDF.
• Над галереей появляется короткое сообщение «Your browser cannot display PDFs here. You can still open or download each PDF.» К нему добавлена подсказка для Chrome, Edge, Firefox или Safari о том, как включить просмотрщик.
• Без JavaScript или если галерея не загрузилась, страница всё равно показывает каждый PDF как миниатюру с именем файла и ссылкой Open PDF in a new tab.

О видео

• YouTube и Vimeo работают через элементы Media типа удалённого видео. Адрес для воспроизведения берётся из поля источника элемента Media.
• В форме плагина Video упоминаются видео HTML5 и Video.js, и встроенная библиотека умеет проигрывать видео HTML5. Но в форматтере поля нет кода, который создаёт слайд из загруженного видеофайла. Элемент Media из файлового типа видео покажется как слайд с изображением, то есть с его миниатюрой. Поэтому мы не называем видео HTML5 поддерживаемым.
• Параметр перехода к следующему слайду после окончания видео не работает с YouTube. Об этом говорится и в форме плагина.

Как это устроено внутри

• Галерея построена на React и компоненте lightGallery для React. Vite собирает их в один файл, js/dist/lightgallery-react.js.
• Сначала сервер выводит обычные ссылки и миниатюры. Когда скрипт загружается, их заменяет интерактивная галерея. Если скрипт не загрузился, обычные ссылки остаются.
• Встроенные версии это lightGallery 2.9.0 и React 18.
• jQuery не используется.

Подмодули

Оба подмодуля необязательные.

LightGallery Formatter Preview

Добавляет в форму профиля кнопку Generate Preview, чтобы вы могли увидеть галерею с текущими настройками до сохранения. В нём также лежат примеры Media с изображением, PDF и удалённым видео для предпросмотра и демонстрации, включая пример миниатюры для PDF.

drush en lightgallery_formatter_preview -y

LightGallery Formatter Demo

Создаёт демонстрационные материалы для проверки галерей с изображениями, PDF файлами и видео. Он рассчитан на установочный профиль demo_umami и использует примеры Media из модуля Preview. При установке он также выбирает миниатюру PDF из модуля Preview для демонстрационного отображения. Мы советуем включить его, если вы хотите увидеть возможности модуля.

drush en lightgallery_formatter_demo -y

Экспорт конфигурации и перенос на другой сайт

Каждый профиль это конфигурация Drupal, которая сохраняется как lightgallery_formatter.profile.{machine_name}. В ней есть машинное имя, название, флаг включения и настройки плагинов. Экспортируйте и импортируйте её так же, как остальную конфигурацию сайта. Соберите профиль на сайте для разработки, экспортируйте его и затем разверните на рабочем сайте.

Настройки форматтера поля, включая выбранный профиль и миниатюру PDF, хранятся в конфигурации отображения этого поля (core.entity_view_display...). Миниатюра PDF сохраняется как идентификатор Media, поэтому проверьте, что этот элемент Media есть на целевом сайте.

drush config:export drush config:import

Совместимость и выпуски

• 1.1.0. Выпущена 1 октября 2026 года (тег в git датирован 28 сентября). Работает с Drupal ^10.3 || ^11 || ^12.
• 1.0.9. Выпущена 20 марта 2026 года. Работает с Drupal ^10.3 || ^11.

Что нового в 1.1.0

• Поддержка PDF в одной галерее с изображениями и удалённым видео
• Общая миниатюра PDF, которая выбирается для каждого отображения поля через Media Library
• PDF файлы открываются в просмотрщике браузера, с понятным запасным вариантом и сообщением, если просмотрщик выключен
• Клонирование профилей из списка профилей (Operations → Clone)
• Совместимость с Drupal 12
• Media Library из ядра теперь обязательная зависимость
• Запасная разметка теперь остаётся на странице, пока галерея не загрузилась, и возвращается, если загрузка не удалась
• Более безопасный вывод, так как имена файлов, названия и атрибуты экранируются
• Отчёт о состоянии Drupal показывает версию встроенной lightGallery
• Много новых автоматических тестов

На странице проекта указано, что модуль используют 56 сайтов. На стабильные выпуски распространяется политика Drupal по уведомлениям о безопасности.

Для разработчиков

Для локальной разработки модуль использует ddev-drupal-contrib.

git clone git@git.drupal.org:project/lightgallery_formatter.git cd lightgallery_formatter ddev start ddev lgf:init

Команда ddev lgf:init устанавливает Drupal с профилем demo_umami, включает модуль с демонстрационными материалами и создаёт вход для администратора. Другие команды это ddev phpcs, ddev phpcbf, ddev phpstan и ddev phpunit.

Node.js нужен только если вы хотите менять интерфейсную часть. Исходный код лежит в js/react/, а стили в css/ (Sass). Сборка запускается командой npm run build, которая использует Vite для JavaScript и Sass для CSS. Версия Node указана в .nvmrc. Готовые файлы попадают в js/dist/.

Ссылки

• Страница проекта https://www.drupal.org/project/lightgallery_formatter
• Очередь задач https://www.drupal.org/project/issues/lightgallery_formatter
• Исходный код https://git.drupalcode.org/project/lightgallery_formatter
• Обучающее видео на YouTube (на английском) https://www.youtube.com/watch?v=FyHGh2xYSEo
• Библиотека lightGallery https://www.lightgalleryjs.com/
• Лицензия lightGallery https://www.lightgalleryjs.com/license/

Авторы

• Модуль создали и поддерживают Andrii и Denys.
• Библиотека lightGallery написана Sachin Neravath. Встроенная версия 2.9.0 распространяется под лицензией GPLv3. React тоже входит в модуль, под лицензией MIT.
• Спасибо @bbu23 и @nk_ за идеи по настройкам на основе профилей.
• Скриншоты взяты со страницы проекта на Drupal.org и из обучающего видео на YouTube.