Gallery3x: вставка галерей в визуальный редактор

Вставка галерей в визуальный редактор

Компонент Gallery3x добавляет в визуальный редактор MODX кнопку «Вставить из галереи». Она открывает окно выбора изображений текущего ресурса и вставляет в текст готовый вызов сниппета (или тег <img>) с ID выбранных фото. В зависимости от выбранного «вида вывода» в вызов подставляются разные чанки — сетка Fancybox, карусель, простые миниатюры и т.д.

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

Адаптер выбирается автоматически: скрипты Gallery3x сами определяют, какой редактор загружен на странице, и молча отключаются, если «их» редактора нет. Настройки самих аддонов CKEditor / TinyMCE RTE менять не нужно — кнопка регистрируется программно.

Включение и настройка

Все настройки находятся в системных настройках MODX, пространство имён gallery3x, раздел «Визуальный редактор (RTE)».

Настройка По умолчанию Описание
gallery3x.rte_enable Нет Включает кнопку галереи в визуальном редакторе. Главный выключатель.
gallery3x.rte_templates пусто На каких шаблонах показывать кнопку:
• пусто — использовать список из gallery3x.templates (там же, где вкладка галереи);
• * — на всех шаблонах;
• 5,10 — только на шаблонах с этими ID.
gallery3x.rte_views пусто JSON-массив «видов вывода» для окна вставки. Пусто — стандартный набор (см. ниже).

После включения настройки откройте ресурс с визуальным редактором — кнопка появится в тулбаре (в CKEditor — отдельной группой в конце, в TinyMCE — в конце первого ряда). Если кнопки нет — обновите страницу менеджера со сбросом кэша браузера (Ctrl+F5).

Окно выбора изображений

По клику на кнопку открывается окно со всеми изображениями текущего ресурса:

Режимы вставки

Режим («Что вставить») Что попадёт в текст Поведение
Выбранные фото [[!Gallery3x? &ids=`17,5,42` &tplOuter=`...` &tplThumb=`...`]] Выводятся ровно эти фото, в порядке кликов. Состав фиксированный.
Всю группу (динамически) [[!Gallery3x? &group=`Имя группы` &resource=`12` &tplOuter=`...`]] Выводятся все фото группы. Если позже в группу добавить фото — они появятся на странице автоматически.
Все фото ресурса [[!Gallery3x? &resource=`12` &tplOuter=`...`]] Вся галерея ресурса, тоже динамически.
Вид «Одиночное фото (тег img)» <img src="[[g3xGetImage? &input=`17` &options=`medium`]]" alt="..."> На каждое выбранное фото вставляется отдельный <img>. Размер выбирается в поле «Размер фото» (thumb / small / medium / large / original). Адрес картинки вычисляется по ID при выводе страницы, поэтому переживает перегенерацию превью.

Флажок «Некэшированный вызов» (включён по умолчанию) вставляет тег как [[!Gallery3x?...]]. Для одиночных фото вызов всегда кэшированный — это безопасно и быстрее.

Виды вывода

«Вид вывода» определяет, какая пара чанков подставится в вызов сниппета. Стандартный набор:

Вид tplOuter tplThumb
Fancybox: сетка tpl.Gallery3x.Fancybox.GridOuter tpl.Gallery3x.Fancybox.GridItem
Fancybox: фото + миниатюры tpl.Gallery3x.Fancybox.outer tpl.Gallery3x.Fancybox.thumbItem
Карусель (lightGallery) tpl.Gallery3x.carousel.outer tpl.Gallery3x.carousel.item
Простые миниатюры tpl.Gallery3x.static_thumbnails.outer tpl.Gallery3x.static_thumbnails
Одиночное фото (тег img) специальный вид — вставляет <img>, чанки не используются

Свои виды вывода (gallery3x.rte_views)

Набор видов задаётся JSON-массивом в настройке gallery3x.rte_views. Каждый элемент массива — один пункт выпадающего списка «Вид вывода» в окне вставки.

Важно знать перед настройкой:

Поле Обязательное Описание
key да Уникальный ключ вида (латиницей, без пробелов).
label да Название в выпадающем списке окна вставки.
tplOuter да Чанк-обёртка, подставится в &tplOuter.
tplThumb обычно да Чанк элемента, подставится в &tplThumb. Можно опустить, если обёртка сама перебирает файлы (Fenom/@INLINE, см. пример 6).
snippet нет Имя вызываемого сниппета. По умолчанию Gallery3x (пример 5).
fenom нет true — добавить в вызов &fenom=`1` (чанки в синтаксисе Fenom, нужен pdoTools).
extra нет Строка с любыми дополнительными параметрами сниппета, добавляется в конец вызова как есть: &limit, &offset, &sortby, &sortdir, &where, &showInactive и т.д.

Пример 1. Стандартный набор + свой вид

Самый частый случай: оставить всё как было и добавить один свой вид. Ниже — полный JSON стандартного набора, к которому в конец добавлен вид «Моя сетка» на собственных чанках:

[
  {"key": "fancybox_grid", "label": "Fancybox: сетка", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem"},
  {"key": "fancybox", "label": "Fancybox: фото + миниатюры", "tplOuter": "tpl.Gallery3x.Fancybox.outer", "tplThumb": "tpl.Gallery3x.Fancybox.thumbItem"},
  {"key": "carousel", "label": "Карусель (lightGallery)", "tplOuter": "tpl.Gallery3x.carousel.outer", "tplThumb": "tpl.Gallery3x.carousel.item"},
  {"key": "static", "label": "Простые миниатюры", "tplOuter": "tpl.Gallery3x.static_thumbnails.outer", "tplThumb": "tpl.Gallery3x.static_thumbnails"},
  {"key": "my_grid", "label": "Моя сетка", "tplOuter": "tpl.My.GridOuter", "tplThumb": "tpl.My.GridItem"}
]

При выборе «Моя сетка» и трёх фото в текст вставится:

[[!Gallery3x? &ids=`17,5,42` &tplOuter=`tpl.My.GridOuter` &tplThumb=`tpl.My.GridItem`]]

Пример 2. Fenom-виды на готовых чанках компонента

В составе Gallery3x уже есть Fenom-варианты чанков Fancybox — их можно подключить отдельными видами (нужен pdoTools):

[
  {"key": "fancybox_grid", "label": "Fancybox: сетка", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem"},
  {"key": "fb_grid_fenom", "label": "Fancybox: сетка (Fenom)", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter.fenom", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem.fenom", "fenom": true}
]

Что вставится:

[[!Gallery3x? &ids=`17,5,42` &tplOuter=`tpl.Gallery3x.Fancybox.GridOuter.fenom` &tplThumb=`tpl.Gallery3x.Fancybox.GridItem.fenom` &fenom=`1`]]

Пример 3. Дополнительные параметры через extra: лимит и сортировка

Поле extra — точка расширения: любые параметры сниппета Gallery3x допишутся в конец вызова. Вид «Последние 6 фото» (удобен с режимами «Вся группа» / «Все фото ресурса» — лимит и сортировка применятся к динамической выборке):

[
  {"key": "last6", "label": "Последние 6 фото", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem", "extra": "&limit=`6` &sortby=`createdon` &sortdir=`DESC`"}
]

Что вставится (режим «Все фото ресурса»):

[[!Gallery3x? &resource=`12` &tplOuter=`tpl.Gallery3x.Fancybox.GridOuter` &tplThumb=`tpl.Gallery3x.Fancybox.GridItem` &limit=`6` &sortby=`createdon` &sortdir=`DESC`]]

Пример 4. Фильтр по полям через &where (экранирование кавычек)

Параметр &where принимает JSON — внутри значения настройки его кавычки надо экранировать обратной косой: \". Вид «Только особенные фото» (поле special, звёздочка в галерее):

[
  {"key": "special", "label": "Только особенные фото", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem", "extra": "&where=`{\"special\":1}`"}
]

Аналогично можно фильтровать по любым полям изображения: {\"extra_num\":2024}, {\"description:!=\":\"\"} и т.д.

Пример 5. Свой сниппет вместо Gallery3x

Если у вас есть сниппет-обёртка со своей логикой (свои дефолты, кэширование, обработка), укажите его в поле snippet — кнопка будет вставлять вызов именно его, передавая те же параметры (&ids / &group / &resource и чанки):

[
  {"key": "my_slider", "label": "Слайдер (свой сниппет)", "snippet": "MySlider", "tplOuter": "tpl.MySlider.outer", "tplThumb": "tpl.MySlider.item", "extra": "&autoplay=`1` &interval=`5000`"}
]

Что вставится:

[[!MySlider? &ids=`17,5,42` &tplOuter=`tpl.MySlider.outer` &tplThumb=`tpl.MySlider.item` &autoplay=`1` &interval=`5000`]]

Пример 6. @INLINE-шаблон без отдельного чанка (продвинутый, нужен pdoTools)

С "fenom": true обёртку можно задать прямо строкой @INLINE — без создания чанка. Внутри доступен массив $files (все поля фото + URL всех размеров: small_url, medium_url, large_url, original_url). tplThumb в этом случае не нужен:

[
  {"key": "inline_row", "label": "Ряд миниатюр (inline)", "fenom": true, "tplOuter": "@INLINE {foreach $files as $f}<a href=\"{$f.original_url}\"><img src=\"{$f.small_url}\" alt=\"{$f.alt}\"></a>{/foreach}"}
]

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

Типовые ошибки

Изменения в сниппетах

Gallery3x: параметр &ids

&ids=`17,5,42` — вывод конкретных изображений по их ID (именно этот параметр использует режим «Выбранные фото»).

g3xGetImage: размер original

[[g3xGetImage? &input=`17` &options=`original`]] теперь возвращает URL оригинального файла (раньше были доступны только размеры превью: thumb, small, medium, large).

Возможные проблемы и решения

Симптом Причина и решение
Кнопки нет в тулбаре Проверьте: gallery3x.rte_enable = Да; шаблон ресурса входит в gallery3x.rte_templates (или gallery3x.templates, если первая пуста); страница менеджера обновлена с Ctrl+F5.
Кнопка без иконки (пустой квадрат) Браузер держит старый CSS/JS — обновите менеджер с Ctrl+F5.
CKEditor: кнопки нет при нестандартном тулбаре Если тулбар CKEditor задан нестандартной конфигурацией, добавьте кнопку Gallery3x в неё вручную.
TinyMCE: в сохранённом тексте &amp; вместо & внутри тега MODX Это нормально: MODX-парсер понимает &amp; в параметрах тегов, вывод работает.
TinyMCE искажает src у одиночного фото Зависит от настроек конвертации URL аддона — установите tinymcerte.relative_urls = Нет.
Галерея не выводится на странице Убедитесь, что чанки выбранного вида существуют, а вызов вставлен некэшированным ([[!...]]), если содержимое должно обновляться.

Техническая справка

Данные окно берёт через штатный коннектор компонента (connector.php, процессоры File\GetList и процессор групп из gallery3x.groups_processor) — работает только в контексте менеджера с активной сессией.

Чтобы подключить другой редактор, достаточно написать новый адаптер, который по своему событию вызывает Gallery3x.rte.openPicker(function (html) { /* вставка html в редактор */ }).