Начало работы

Здесь — что нужно подготовить перед установкой, какие настройки задать сразу в окне установки и почему это важно сделать до первой нарезки. Когда окружение готово и настройки выставлены, переходите к Разметке вёрстки — с неё начинается реальная работа.

Требования к окружению

• MODX Revolution 2 (тестируется на ветке 2.8.x). MODX 3 пока не поддерживается — адаптация в планах.
• PHP 7.4 — минимально необходимая и рекомендуемая версия. На PHP 8.x стабильность не гарантируется.
• Расширение PHP zip — нужно для экспорта лексиконов в XLSX.

Подсказка

Сторонние библиотеки (DiDOM — разбор HTML, OpenSpout — выгрузка XLSX) уже входят в пакет, отдельно их ставить не нужно.

Зависимости

Обязательные:

• pdoTools — рендеринг секций (шаблонизатор Fenom + parseChunk). Без него компонент не работает.
• MIGX — хранилище полей секции. Данные лежат в его конфигурациях и редактируются его привычным гридом.

Поставить их можно через «Управление дополнениями» в админке или с modstore.

Для обрезки изображений (опционально):

Миниатюры формирует сниппет, указанный в системной настройке mpc_thumb_snippet. По умолчанию это mpcThumb — встроенная в пакет обёртка над pThumb (сначала проверяет, что файл существует, и только потом отдаёт его на обрезку, чтобы не сыпать ошибки в лог). То есть «из коробки» обрезка работает через pThumb, и его нужно установить. Жёсткой зависимости при этом нет: значение настройки можно заменить любым другим thumb-сниппетом (например phpThumbOf) или очистить — тогда картинки выводятся без обрезки. Отключить обрезку у отдельной картинки можно атрибутом data-mpc-nothumb.

Шаблонизатор Fenom

Обязательно

Шаблоны и чанки сайта должны обрабатываться через Fenom. Включите системную настройку pdotools_fenom_parser = Да (Fenom поставляется в составе pdoTools).

Настройки в окне установки

При первой установке пакет показывает окно с базовыми настройками. Введённые значения сразу записываются в системные настройки MODX (на повторной установке/обновлении окно подставит уже сохранённые значения и не перетрёт ваши). Позже всё это можно изменить и в разделе «Системные настройки».

Почему удобнее задать сразу

Режим лексиконов и список языков определяют формат хранения контента уже с первой нарезки: при включённом режиме переводимые значения уходят в lexicon-файлы, а в плейсхолдеры добавляется | lexicon. Переключить режим можно и потом — но тогда понадобится перенарезать все шаблоны (mgr_tpl.php), чтобы значения переехали из конфига в лексиконы (см. Лексиконы и мультиязычность). Операция штатная, просто лишняя — поэтому с языками удобнее определиться здесь, до начала работы.

Окно сгруппировано по разделам.

Лексиконы

Определяют мультиязычность и формат хранения переводимого контента (подробно — в разделе Лексиконы и мультиязычность).

• Использовать лексиконы (мультиязычность) (mpc_use_lexicons) — главный переключатель режима. Включено — при нарезке переводимые значения выносятся в lexicon-файлы, а в плейсхолдер добавляется модификатор | lexicon. Это и есть момент, который определяет всю дальнейшую работу: меняете его после нарезки — нужна перенарезка.
• Namespace лексиконов (mpc_lexicons_namespace) — пространство имён, в котором создаются лексиконы. По умолчанию migxpageconfigurator.
• Путь к лексиконам (mpc_lexicon_path) — куда складываются файлы лексиконов. Важно: путь должен соответствовать пространству имён из mpc_lexicons_namespace — лексиконы загружаются штатными средствами MODX ($modx->lexicon), а он ищет файлы по пути, привязанному к namespace. Рассинхрон пути и namespace → переводы не подхватятся.
• Файл исключений лексиконов (mpc_exclude_lexicons_filename) — список полей, которые переводить не нужно.
• Доступные языки (mpc_available_languages) — коды языков сайта через запятую (ru,en). Это те же коды, что MODX использует для языковых папок лексиконов (lexicon/ru/, lexicon/en/) и для cultureKey контекста. Пусто — сайт одноязычный. Для всех перечисленных синхронизируется набор lexicon-ключей.
• Язык по умолчанию (mpc_default_language) — код основного языка (ru). В его lexicon-файл пишутся значения при нарезке; остальные языки получают эти же значения как плейсхолдер — до тех пор, пока их не переведут.

Медиа

• Ленивая загрузка (lazyload) (mpc_lazyload_enabled) — глобальный выключатель lazyload. Выкл — JS ленивой загрузки не подключается, картинки грузятся сразу.
• Разворачивание SVG (expand) (mpc_expand_enabled) — глобальный выключатель «разворачивания» SVG. Разворачивание — это замена картинки-ссылки на SVG (<img> с атрибутом data-svg, по умолчанию) на инлайновый код <svg> прямо в разметке: при появлении элемента в зоне видимости его содержимое подгружается и <img> подменяется на <svg> (атрибуты width/height/id/class переносятся). Зачем это нужно: иконку, вставленную как <img src="icon.svg">, нельзя стилизовать и анимировать через CSS и нельзя обращаться к её внутренним элементам — а инлайновый <svg> всё это позволяет (перекрасить через fill/currentColor, анимировать, менять части по скрипту). Выкл — SVG не разворачиваются и остаются обычными <img>.

Пути

• Путь к пресетам (mpc_path_to_presets) — папка, где лежат файлы пресетов параметров для вызовов сниппетов (см. Работа со сниппетами). Путь задаётся относительно pdotools_elements_path. Эту настройку важно задать сразу, до начала работы: по умолчанию пресеты могут оказаться внутри папки самого пакета, а там они затрутся при обновлении компонента. Укажите путь вне пакета (например, в проектную папку шаблонов) — тогда пресеты переживут переустановки.

• Путь к манифестам mpc CLI (mpc_manifests_path) — базовая папка с манифестами для команд apply консольного CLI (относительно core/ или абсолютный; переопределяется переменной окружения MPC_MANIFESTS_PATH). Сам CLI используется шире — в том числе для нарезки (cut) и очистки кэша; манифесты же нужны именно командам apply. Идея простая: вы описываете в файле, что должно быть на сайте, запускаете команду — и она создаёт недостающее и обновляет изменившееся. Запускать можно сколько угодно раз: повторный прогон ничего не ломает и не плодит дубли. Так настраивают:

  • resources apply — дерево ресурсов;
  • settings apply — системные и контекстные настройки MODX;
  • clientconfig apply — настройки ClientConfig;
  • events apply — привязки плагинов к событиям;
  • packages apply — установка/удаление пакетов.

  Если положить боевые манифесты в эту папку, путь команде можно не передавать (resources apply сам возьмёт resources.php отсюда). Готовые шаблоны для копирования лежат в core/components/migxpageconfigurator/console/examples/ (resources.example.php, settings.example.php, clientconfig.example.php, plugins.example.php, packages.example.php).

Остальные системные настройки

Кроме базовых, у компонента есть ещё около полусотни системных настроек. Большинство имеют разумные значения по умолчанию — здесь обзор от тех, что чаще всего стоит проверить, до чисто косметических. Полный справочник со значениями по умолчанию — в разделе Справочник системных настроек.

Стоит проверить под проект

• mpc_media_source — источник файлов (modMediaSource), куда грабер складывает скачанные медиа. При установке пакет сам создаёт выделенный источник mpcMedia (файловый, с разрешёнными типами картинок/видео/аудио) и прописывает его id в эту настройку — то есть из коробки она уже заполнена, менять обычно не нужно. Если значение очистить, грабер использует системный источник по умолчанию (default_media_source); если и его нет — медиа не скачивается и в лог пишется ошибка.
• mpc_media_path — базовый путь медиа внутри источника, под ним создаются подпапки images/videos/audios. См. также Работа с медиа.
• mpc_thumb_snippet и mpc_common_thumb_params (q=90&zc=1&f=webp) — сниппет обрезки и общие параметры миниатюр.
• mpc_edit_mode — режим редактирования для визуального редактора mpcVisualEditor: при нарезке в чанках сохраняются маркеры data-mpc-*. Включать, только если используете mpcVE (после включения — перенарезать).
• mpc_dev_mode — режим разработки: при каждом запуске нарезки чистится кэш компонента и сайта. Удобно на этапе натяжки, на проде — выключить.
• mpc_download_extensions и mpc_download_paths — какие расширения грабер вообще скачивает (белый список) и в какие подпапки раскладывать медиа по типу. Важно: тип (images/videos/audios/others) определяется по тегу элемента в разметке (<img>/<picture> → images, <video> → videos, <audio> → audios, остальное → others), а не по расширению файла. Расширение лишь решает, качать ли файл; а для ссылок без расширения оно достраивается по Content-Type через карту MIME→расширение (mpc_mime_to_ext_path → elements/media/mime_to_ext.json). Подробнее — в разделе Работа с медиа.
• mpc_editable_resource_fields / mpc_protected_resource_fields — какие нативные поля ресурса разрешено писать через разметку (data-mpc-rfield), а какие защищены от перезаписи.
• mpc_allowed_tags / mpc_allow_modx_tags — какие HTML-теги сохраняются в значениях лексиконов и разрешать ли в них теги MODX/Fenom (по умолчанию запрещены — безопаснее).

Пути файлов компонента

Пять путей задают, где лежат исходники и куда складываются сгенерированные файлы. Важно: все они задаются относительно pdotools_elements_path (а не от core/ и не от корня сайта) — то есть отсчитываются от той же базовой папки, что и обычные файловые элементы pdoTools.

• mpc_path_to_src (templates/) — исходники: размеченная вёрстка, файлы-шаблоны. Это источник истины, который вы редактируете и режете. Всё остальное генерируется из него.
• mpc_path_to_sections (sections/) — результат нарезки: файлы-секции, на которые компонент раскладывает шаблон. Править их вручную не нужно — изменения вносятся в исходник и применяются повторной нарезкой.
• mpc_path_to_chunks (chunks/) — вырезанные чанки: куски вёрстки, вынесенные атрибутом data-mpc-chunk (шаблоны строк списков, обёртки, подключаемые блоки — см. Работа с чанками).
• mpc_path_to_dist (parsed/) — кэш рендера: «запечённые» страницы с уже подставленными значениями. Заполняется на нарезке или сохранении ресурса, чтобы не парсить конфиг на каждый запрос. Чистится вместе с кэшем компонента.
• mpc_path_to_presets (presets/) — пресеты параметров для вызовов сниппетов (см. Работа со сниппетами). Эту папку стоит задать сразу в окне установки и держать вне папки пакета, иначе пресеты затрутся при обновлении компонента.

Подсказка

Папки исходников и пресетов (src, presets) держите в репозитории проекта — это ваш рукотворный контент. Папки sections, chunks, parsed — генерируемые, их можно не версионировать.

Заполняются при установке автоматически

Эти настройки обычно проставляются сами при установке и нарезке — трогать их вручную, как правило, не нужно: mpc_config_tv_id, mpc_contacts_page_id, mpc_contacts_tv_id, mpc_static_block_page_id, mpc_tmplvar_ids.

Тонкая настройка лексиконов и контактов

mpc_translated_content (типы контента, требующие перевода), mpc_contact_lexicon_fields (какие поля контакта переводятся), mpc_cmp_resource_label_field (подпись ресурса в интерфейсе лексиконов), mpc_phone_format / mpc_phone_regexp (форматирование телефонов — см. Работа с контактами).

Отдельно про mpc_lexicon_filename_field — что подставлять в имя файла лексикона, alias или id ресурса:

• alias — если на сайте несколько контекстов с похожей структурой страниц (одни и те же страницы на разных языках/доменах). Совпадающие алиасы дадут общий файл лексикона, и переводы переиспользуются между контекстами.
• id — если контексты никак не связаны между собой и структура страниц разная. Привязка по id гарантирует, что лексиконы контекстов не пересекутся.
• Если контекст один — разницы в поведении нет, но alias нагляднее (по имени файла сразу видно, к какой странице он относится).

Косметические и служебные (обычно по умолчанию)

Пути и служебные имена, которые редко требуют изменения: mpc_path_to_samples, mpc_tpl_file_extension, mpc_wrapper_name, mpc_base_section_name, mpc_common_config_name, mpc_contacts_tv_name, mpc_lazyload_attr, mpc_fake_img_path, mpc_expand_attr, mpc_tv_category, mpc_exclude_fields_path, mpc_mime_to_ext_path.

---

Окружение готово, зависимости стоят, базовые настройки выставлены — дальше начинается главное: Разметка вёрстки.