docs.modx.pro

Русский

English

Русский

English

Тема

  1. Компоненты
  2. MigxPageConfigurator
  3. Работа с медиа

Работа с медиа ​

Компонент берёт на себя всю работу с медиа при нарезке: скачивает внешние файлы в ваш медиа-источник, подключает обрезку картинок и ленивую загрузку, разбирает видео и аудио вместе с их источниками. Ниже — от того, куда складываются файлы, к обрезке, ленивой загрузке и видео/аудио.

Источник файлов ​

Все медиа, которые компонент скачивает при нарезке, сохраняются не «куда-то на диск», а через медиа-источник MODX (modMediaSource) — тот же механизм, что и у файлового менеджера админки. Источник задаётся настройкой mpc_media_source (id медиа-источника).

  • Если mpc_media_source задан — файлы складываются в него (с учётом его настроек: путь, права, обработчики).
  • Если пусто — берётся медиа-источник MODX по умолчанию (default_media_source).

Внутри источника файлы раскладываются по подпапкам: базовый путь mpc_media_path → подпапка по типу медиа (images / videos / audios / others) → при необходимости подпапка с именем секции. Подпапки по типам можно переопределить настройкой mpc_download_paths (JSON вида {"images":"img","videos":"video"}). Нужные контейнеры компонент создаёт сам, а в разметку подставляет публичный URL файла, который вернул источник.

Зачем через медиа-источник

Так скачанные картинки попадают туда же, куда менеджер загружает файлы вручную, видны в файловом менеджере и подчиняются правам и обработчикам источника. Визуальному редактору этот же источник нужен для загрузки картинок со страницы — см. Медиа и файлы в доке mpcVisualEditor.

Скачивание внешних файлов ​

Если у картинки, видео или аудио в src (или poster, или <source src>) стоит внешний адрес (http://… / https://…), нарезка скачивает файл к вам в медиа-источник и подставляет в разметку уже локальный URL. Это удобно при натяжке вёрстки с CDN или стоковыми ссылками — после нарезки сайт не зависит от чужих доменов.

Что важно знать:

  • скачиваются только разрешённые расширения — список в настройке mpc_download_extensions;
  • расширение файла определяется сначала по адресу, затем — если в адресе его нет — по типу содержимого (см. ниже про MIME);
  • есть защита: компонент не качает с внутренних/локальных адресов и отбрасывает файлы с подозрительным содержимым (например, замаскированный под картинку скрипт);
  • при ошибке скачивания в разметке остаётся исходный внешний адрес — страница не ломается.

Локальные пути (без http) не трогаются — они и так на вашем сайте.

MIME и расширение ​

Когда файл скачивается по адресу без расширения, компонент определяет его по типу содержимого (заголовок Content-Type) и карте соответствий MIME → расширение. Карта — это файл elements/media/mime_to_ext.json (путь можно переопределить настройкой mpc_mime_to_ext_path):

json
{
  "image/jpeg": "jpg",
  "image/png": "png",
  "video/mp4": "mp4",
  "audio/mpeg": "mp3"
}

Если типа нет в карте или расширение не входит в mpc_download_extensions — файл не сохраняется.

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

Если у картинки заданы атрибуты width и height, компонент подключает к ней обрезку через сниппет-миниатюрщик. Сниппет задаётся настройкой mpc_thumb_snippet (по умолчанию mpcThumb), а общие параметры обрезки — настройкой mpc_common_thumb_params (по умолчанию q=90&zc=1&f=webp — качество 90, обрезка по размеру, формат WebP).

Для картинки в разметке:

html
<img data-mpc-field="img" src="assets/img/cover.png" width="320" height="200" alt="">

на выходе в файле секции получится вызов миниатюрщика, которому в параметры подставляются ширина и высота из полей:

fenom
<img
  src="assets/components/migxpageconfigurator/images/fake-img.png"
  data-lazy="{'mpcThumb' | snippet: ['input' => $img[0].src, 'options' => 'q=90&zc=1&f=webp&w='~$img[0].width~'&h='~$img[0].height]}"
  alt="{$img[0].title}">

То есть width/height — не просто HTML-атрибуты: их значения уходят в обрезку, и под каждый размер генерируется свой вызов миниатюры. У адаптивных картинок (<picture>) каждый <source> обрезается под свой размер.

Отключить обрезку для конкретной картинки — атрибутом data-mpc-nothumb.

Когда обрезка не подключается

Обрезка работает, если задан mpc_thumb_snippet. Без сниппета-миниатюрщика компонент просто подставит ссылку на картинку как есть.

Ленивая загрузка ​

В комплекте идёт скрипт ленивой загрузки: реальный адрес картинки прячется в атрибут mpc_lazyload_attr (по умолчанию data-lazy), а в src ставится лёгкая заглушка (mpc_fake_img_path). Картинка подгружается, когда попадает в область видимости.

Включается ленивая загрузка настройкой mpc_lazyload_enabled; имя атрибута — mpc_lazyload_attr (очистка отключит механизм). Скрипт подключается на страницу автоматически.

Иногда картинка изначально скрыта (внутри слайдера, таба, аккордеона) и не попадает в зону видимости — тогда её можно загрузить принудительно. Скрипт доступен глобально как window.mpcLazyLoad, у него есть метод loading(element):

js
// форс-загрузка картинок внутри только что открытого слайда
slide.querySelectorAll('[data-lazy]').forEach((el) => window.mpcLazyLoad.loading(el));

Отключить ленивую загрузку для конкретного элемента — атрибутом data-mpc-nolazy.

Инлайн SVG ​

Чтобы SVG-иконку можно было стилизовать через CSS (менять цвет, размеры), её удобно вставлять инлайном в разметку, а не через <img>. Для этого пометьте элемент атрибутом mpc_expand_attr (по умолчанию data-svg): скрипт mpcExpand подгрузит файл и заменит элемент на содержимое SVG (перенеся width/height/class/id). Включается настройкой mpc_expand_enabled.

html
<img src="assets/img/icon.svg" data-svg width="24" height="24">

Видео и аудио ​

Видео и аудио размечаются так же, как картинки, — атрибутом data-mpc-field на теге <video> или <audio>. Компонент переносит в админку все их атрибуты и вложенные источники:

  • видео — src, poster, width, height, title, а также autoplay, controls, loop, muted, preload;
  • аудио — то же, без poster/width/height;
  • источники <source> — src/srcset, type, media, sizes.

Логические атрибуты (autoplay, controls, loop, muted) хранятся как «да/нет» и подставляются в вывод условно. Если у самого <video>/<audio> нет src, берётся первый <source>. Внешние адреса (http) у src, poster и источников скачиваются в медиа-источник так же, как картинки.

Точный список под-полей видео и аудио и обращение к ним из шаблона — в разделе Справочник типов полей.