Изображения, галереи, файлы

Файловый менеджер и источник файлов

Изображения и файлы выбираются в стандартном файловом менеджере MODX (Media Browser) — в том же окне, что открывается у TV типа «Изображение». Редактор не строит адреса файлов сам: он записывает URL, который вернул MODX, поэтому работает любой источник файлов (Media Source) — файловая система, S3 или собственный.

Какой источник использует поле:

• TV типа Rich Text — источник, назначенный этому TV для контекста ресурса;
• поле «Содержимое» — источник из tiptapeditor.media_source (ID), а если он пуст — default_media_source контекста.

Права. Файловый менеджер доступен, только если у пользователя есть право file_manager, а источник разрешает просмотр (list). Иначе кнопка Ссылка на файл неактивна, а в диалоге изображения нет кнопки выбора файла — можно только ввести адрес. Сам файловый менеджер проверяет те же права при каждом запросе.

Формат адреса задаёт tiptapeditor.media_url_mode:

Значение	Что записывается
relative (по умолчанию)	URL ровно как вернул MODX, например assets/img/a.jpg — как в TV «Изображение».
root	К относительному URL добавляется base URL сайта: /assets/img/a.jpg.

Абсолютные адреса (S3 и другие удалённые источники) всегда сохраняются как есть. В самом редакторе относительные адреса картинок показываются относительно сайта, но в содержимом src остаётся без изменений.

Если окно файлового менеджера не открывается

Основной путь — окно файлового менеджера прямо на странице. Если оно недоступно, редактор открывает отдельную страницу файлового менеджера во всплывающем окне; выбранный файл передаётся обратно в редактор. Разрешите всплывающие окна для адреса менеджера, если браузер их блокирует.

Изображения

Кнопка «Изображение» и диалог

Кнопка Изображение открывает диалог «Вставить изображение». Если выделено изображение, тот же диалог называется «Изменить изображение» и правит его.

Взять картинку можно тремя способами — кнопками под полем Адрес изображения:

Кнопка	Что делает	Когда есть
Выбрать в файловом менеджере…	Открывает файловый менеджер в папке текущего файла; выбранный файл подставляется в адрес. Не-изображения отклоняются с сообщением.	Есть доступный источник файлов
Загрузить с компьютера…	Выбор файла на компьютере, загрузка в папку tiptapeditor.upload_path источника файлов поля.	Включена загрузка
Скачать на сайт	Скачивает картинку по адресу из поля на сервер (в ту же папку загрузок) и подставляет локальный адрес. Страница больше не зависит от чужого сайта.	Включена загрузка

Можно и просто вписать адрес вручную, например https://…, /assets/img/a.jpg или [[+image]].

Остальные поля диалога:

Поле	Что делает
Превью и Исходный размер W × H	Превью выбранной картинки. Кнопка с исходным размером подставляет его в ширину и высоту, сама по себе ничего не применяется.
Альтернативный текст (alt)	Описание для тех, кто не видит картинку. Для декоративного изображения оставьте пустым.
Подсказка (title)	Атрибут title.
Подпись	Текст под изображением (<figcaption>), например источник. См. Подписи.
Увеличение по клику	Ссылка на картинку вокруг неё для лайтбокса сайта. См. «Увеличение по клику».
Ширина, Высота	Целое число пикселей (640) или процент (100%).
Выравнивание	Нет, По левому краю, По центру, По правому краю — записывается классом align-left, align-center или align-right.
Стиль	Пресет класса из tiptapeditor.image_classes. Поле есть, если пресеты заданы.
Другие CSS-классы	Остальные классы (без пресетов поле называется CSS-класс).

Внизу — Удалить изображение (для существующего), Отмена и Сохранить.

Классы выравнивания нужны и на сайте

Редактор сам показывает align-left, align-center и align-right, но на сайте их надо описать в CSS шаблона. Имена классов можно поменять ключом imageAlignClasses в профиле.

Что ещё важно:

• Все прочие атрибуты существующего <img> сохраняются как написаны: id, data-*, loading, srcset, sizes, style. Редактор показывает картинку без srcset, но сохраняет его без изменений.
• Классы, которых диалог не знает, остаются на месте.
• Если открыть диалог и нажать Сохранить без изменений, изображение не трогается вообще.
• Не принимаются адреса data: (base64), javascript: и другие небезопасные, а также атрибуты-обработчики событий. Абзац с <img onerror="…"> остаётся HTML-блоком: он показывается как текст, и обработчик в менеджере не выполняется.

Меню изображения

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

• Изменить изображение — тот же диалог;
• Заменить файл — файловый менеджер открывается в папке текущего файла; меняется только файл, а alt, title, размеры и остальные атрибуты остаются. Есть, только если у поля есть доступный источник файлов;
• Удалить изображение.

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

Загрузка изображений

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

• в диалоге изображения появятся кнопки Загрузить с компьютера… и Скачать на сайт;
• картинки можно перетаскивать в текст и вставлять из буфера обмена — они загружаются и вставляются в место курсора;
• в диалоге галереи появится загрузка с компьютера и скачивание по ссылке.

Как работает загрузка:

• Файлы сохраняются в папку tiptapeditor.upload_path (по умолчанию assets/uploads/) источника файлов поля.
• Загрузка идёт через штатный механизм MODX: нужны право file_upload и разрешение источника на создание файлов; действуют разрешённые типы файлов источника и системная настройка upload_maxsize.
• Имя файла становится безопасным: транслит, латиница, цифры, дефисы и короткий случайный хвост. Например, Скриншот 1.png → skrinshot-1-x7k2q9.png.
• Изображения никогда не сохраняются в base64.

Без загрузки перетащенные файлы не вставляются: редактор подскажет нажать Изображение и выбрать файл в файловом менеджере. Перетаскивать можно только изображения; для других файлов есть кнопка Ссылка на файл.

Копирование по ссылке и защита сервера

Скачать на сайт (и кнопка Изображение по ссылке, если её добавили на панель) просит сервер скачать картинку с другого сайта. Чтобы этой функцией нельзя было «прощупать» внутреннюю сеть сервера (атака SSRF), сервер скачивает только безопасное:

• только http:// и https://, только стандартные порты 80 и 443, без логина и пароля в адресе;
• адрес должен вести на публичный сайт: localhost, внутренние, служебные и зарезервированные сети запрещены — проверяется каждый IP, в который разрешается имя;
• соединение идёт именно на проверенный адрес, его нельзя подменить между проверкой и скачиванием;
• переадресации проверяются заново, не больше трёх;
• скачивание прерывается, если файл больше upload_maxsize;
• принимаются только настоящие JPEG, PNG, GIF, WebP и AVIF — по содержимому, а не по расширению. SVG по ссылке не скачивается.

Если адрес не подходит, в диалоге появится понятное сообщение, например «Этот адрес использовать нельзя: разрешены только публичные сайты на стандартных портах».

Подписи

Заполните поле Подпись — изображение станет фигурой:

<figure>
    <img src="assets/img/sea.jpg" alt="Море">
    <figcaption>Фото: Иван Петров</figcaption>
</figure>

Подпись можно править и прямо в тексте. Если очистить подпись и выключить «Увеличение по клику», фигура снова становится обычной картинкой.

Существующие <figure> с одним изображением (можно внутри ссылки) и подписью открываются как редактируемые, со всеми атрибутами (srcset, sizes, loading, aria-label и т. д.). Другие фигуры остаются HTML-блоками.

«Увеличение по клику» (лайтбокс)

Флажок Увеличение по клику оборачивает картинку ссылкой на неё же — её подхватит скрипт-лайтбокс вашего сайта (Fancybox, Lightbox и т. п.). Сам скрипт редактор не подключает: он только пишет нужную разметку.

Настройка	Что задаёт
tiptapeditor.lightbox	Включён ли флажок для новых изображений и галерей. В диалоге его можно поменять для каждой картинки.
tiptapeditor.lightbox_attribute	Атрибут, который ищет ваш скрипт: data-fancybox, data-lightbox, data-gallery… Пусто — обычная ссылка.
tiptapeditor.lightbox_label	aria-label ссылки; {alt} заменяется на alt или подпись. Пусто — «Открыть изображение: {alt}» на языке менеджера.

Одиночная картинка получает атрибут без значения, а все картинки одной галереи — одно имя группы. Пример для lightbox_attribute = data-fancybox:

<figure>
    <a href="assets/img/sea.jpg" data-fancybox aria-label="Открыть изображение: Море">
        <img src="assets/img/sea.jpg" alt="Море">
    </a>
    <figcaption>Море</figcaption>
</figure>

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

Галереи

Кнопка Галерея открывает диалог «Вставить галерею». На выделенной галерее (двойной щелчок или Enter) — «Изменить галерею».

Как добавить картинки:

• Добавить из файлового менеджера… — можно выбрать сразу несколько файлов (Ctrl или Shift + щелчок);
• Загрузить с компьютера… — несколько файлов сразу (если включена загрузка);
• поле адреса и кнопка Скачать на сайт, если включена загрузка: картинка копируется в папку загрузок. Без загрузки кнопка называется Добавить, и адрес добавляется как есть.

Для каждой картинки — миниатюра, имя файла, поля alt и Подпись, кнопки Выше, Ниже и Убрать из галереи.

Для всей галереи — Шаблон и Увеличение по клику. Внизу — Удалить галерею (для существующей), Отмена и Вставить / Сохранить.

В тексте галерея выглядит как карточка с миниатюрами. Если изменений не было, разметка галереи в поле остаётся прежней.

Шаблоны

Шаблон	Название в диалоге	Разметка
grid	Сетка	div.gallery с фигурами figure.gallery__item
slider	Слайдер (Swiper)	разметка Swiper: .swiper, .swiper-wrapper, .swiper-slide, пагинация и стрелки
images	Только изображения	div.gallery.gallery--images только с картинками, без подписей

Шаблон новых галерей задаёт tiptapeditor.gallery_template (по умолчанию grid). Стили сетки и скрипт Swiper подключаются на сайте — редактор только пишет разметку.

Пример галереи grid с увеличением:

<div class="gallery" data-tiptapeditor-gallery="grid">
    <figure class="gallery__item">
        <a href="img/1.jpg" data-fancybox="gallery-3fa9c1" aria-label="Открыть изображение: Море"><img src="img/1.jpg" alt="Море"></a>
        <figcaption>Море</figcaption>
    </figure>
</div>

Атрибут data-tiptapeditor-gallery с именем шаблона нужен, чтобы галерею можно было открыть и править снова, — не удаляйте его.

Свои шаблоны

Дополнительные шаблоны задаются JSON-объектом в tiptapeditor.gallery_templates:

{
    "cards": {
        "label": "Карточки",
        "wrapper": "<ul class=\"cards\">{items}</ul>",
        "item": "<li>{image}{caption}</li>"
    }
}

• Имя шаблона — латиница, цифры, _ и -, начинается с буквы.
• label — название в списке «Шаблон».
• wrapper — внешний элемент, ровно один раз содержит {items}.
• item — разметка одной картинки: ровно один {image} (картинка, со ссылкой, если включено увеличение) и не больше одного {caption} (<figcaption> с подписью). Если {caption} нет, поле подписи в диалоге скрывается.
• Скрипты, стили, iframe, формы и атрибуты on* из шаблона удаляются.
• Неверный шаблон молча пропускается. Чтобы увидеть причину, включите tiptapeditor.debug — она появится в консоли браузера.

Шаблоны можно задать и в профиле ключом galleryTemplates.

Ссылки на файлы

Кнопка Ссылка на файл открывает файловый менеджер без фильтра по типу (PDF, DOCX, архивы — что угодно):

• если текст выделен, он становится ссылкой на файл;
• если нет — вставляется имя файла со ссылкой.

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

После обновления

Если tiptapeditor.toolbar у вас настроен вручную, допишите file рядом с image, чтобы кнопка появилась.

Видео и встраивание (iframe)

Кнопка Видео или встраивание открывает диалог:

Поле	Что делает
Адрес видео или код встраивания	Ссылка на YouTube, VK Видео или Rutube, адрес для встраивания или готовый код <iframe>.
Ширина, Высота	Число, можно с px или %. Для нового видео — 560 × 315.
Подсказка (title)	Атрибут title. Есть, если title в списке разрешённых атрибутов.
Разрешить полноэкранный режим	Атрибут allowfullscreen. Есть, если он в списке разрешённых.

Ссылки на страницы видео превращаются в адрес плеера, например https://youtu.be/ID?t=30 → https://www.youtube.com/embed/ID?start=30. Понимаются ссылки YouTube (в том числе Shorts и youtu.be), VK Видео (vk.com, vkvideo.ru) и Rutube. Разработчики могут добавить свои сервисы — см. JS API.

В редакторе iframe — карточка с адресом сайта и размером. Внутри менеджера он никогда не загружается: ни видео, ни чужие скрипты не запускаются. Двойной щелчок или Enter открывает диалог. Неизменённые iframe сохраняются ровно как были.

Настройка	Что задаёт
tiptapeditor.enable_iframe	Кнопка и встраивание вообще.
tiptapeditor.iframe_allowed_hosts	Разрешённые сайты через запятую (поддомены входят). Пусто — любой http(s)-сайт.
tiptapeditor.iframe_allowed_attributes	Атрибуты, которые сохраняются у iframe. Обработчики on* не сохраняются никогда.

Iframe, который не проходит эти правила, не удаляется — он остаётся HTML-блоком.