MigxPageConfigurator

Какие задачи решает

1. Переносит контент из вёрстки в админку при натяжке

При обычной интеграции вёрстки на каждый редактируемый блок приходится вручную вырезать чанк, написать его вызов и перенести тексты с картинками в TV. MPC убирает эту рутину: вы один раз размечаете HTML атрибутами data-mpc-* и запускаете нарезку (mgr_tpl.php). Дальше компонент сам:

• вырезает размеченные элементы в файлы-секции и чанки, подставляя на их место вызовы Fenom;
• переносит значения полей (текст, ссылки, src/alt/title изображений) в админку — в TV mpc_config на базе MIGX;
• картинкам с заданными width/height подключает обрезку через pThumb и lazy-load (см. Работа с медиа);
• собирает вызовы сниппетов (data-mpc-snippet) и подключаемые/обрабатываемые чанки (data-mpc-chunk, data-mpc-include, data-mpc-parse) — см. Работа со сниппетами и Работа с чанками.

Верстальщик не пишет вызовы сниппетов и PHP руками — этим занимается нарезка.

2. Держит разметку в одном источнике — файлах-шаблонах

Источник истины — исходный файл шаблона и файл-обёртка с общим HTML. Нарезка детерминированно раскладывает шаблон на файлы-секции и чанки; правки вносятся в шаблон и применяются повторным запуском скрипта, а сгенерированные файлы секций трогать не нужно (и не следует — см. Рендеринг). Путь к файлу каждой секции виден в поле file_name. В итоге не приходится искать нужный чанк среди десятков разрозненных — структуру задаёт один шаблон, и она же лежит в репозитории.

3. Централизованно хранит данные и даёт их переиспользовать — на привычном MIGX

Все данные секции лежат в одном TV mpc_config (JSON) и редактируются через грид и формы MIGX — интерфейс, знакомый большинству MODX-разработчиков, без отдельного «кабинета». Переиспользование данных обеспечивают:

• статические секции — один контент на всех страницах (шапка, подвал, сквозные блоки), хранится в ресурсе «Типы страниц»;
• наследование типа страницы — ресурс-донор (дочерний к «Типы страниц», тот же шаблон) задаёт значения по умолчанию для всех страниц своего типа;
• копирование секций между типами (Дополнить / Перезаписать / Очистить);
• контакты — единое хранилище телефонов, почт, адресов и соцсетей с выводом сниппетом.

Каскад «глобально → тип → ресурс» позволяет задать данные один раз на уровне типа и точечно переопределить их на конкретной странице.

4. Расширяет управление контентом без россыпи TV

Вместо отдельного TV под каждое поле все поля секции живут в одном mpc_config. Это снимает боль «десятки TV на шаблон» и добавляет:

• произвольные имена полей секции — нужное поле заводится прямо разметкой, без создания TV;
• списки повторяющихся блоков через вложенный MIGX — динамическое число элементов (карточки, слайды, пункты), а не фиксированные слоты;
• условный вывод элементов (data-mpc-cond), скрытие секций (hide_section) и их переупорядочивание (position);
• разные типы полей внутри конфига (текст, изображение, ссылка, listbox, чекбокс и т.д. — см. Создание и обновление элементов).

5. Улучшает нативный механизм переводов

MODX умеет в лексиконы, но вести их вручную под контент трудоёмко. MPC автоматизирует перевод (см. Лексиконы и мультиязычность): на нарезке переводимые значения выносятся в lexicon-файлы, а в плейсхолдеры добавляется модификатор | lexicon. Сверху этого:

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

Что ещё закрывает

• Сопровождаемость и аудит. Правки контента из админки логируются (кто, когда и что менял), на нарезке собирается манифест трекаемых полей — см. Аудит правок; просмотр истории и откат доступны в визуальном редакторе (пакет mpcVisualEditor). Разметка и код секций лежат в репозитории, а не размазаны по чанкам в БД.
• Скорость ответа сервера. Конфигурации парсятся не на каждый запрос, а на нарезке или при сохранении ресурса (кэш elements/parsed) — см. Рендеринг.
• Разделение ролей. Верстальщик размечает шаблон, контент-менеджер правит значения в админке, не зная HTML.

Кому и для каких сценариев подходит

• Сайты, которые собираются «натяжкой» готовой вёрстки и где контент-менеджер должен править блоки без знания HTML.
• Многостраничники с типовыми шаблонами (услуги, посадочные, разделы каталога): страницы одного типа повторяют структуру, но отличаются контентом.
• Проекты со сквозными блоками (шапка, подвал, CTA-формы), которые нужно править в одном месте сразу для всех страниц.
• Мультиязычные сайты, где контент переводится без дублирования ресурсов под каждый язык.
• Проекты, где важна сопровождаемость и история изменений: разметка под версионным контролем, правки контента — под аудитом.

Подсказка

Компонент рассчитан на разработчика, знакомого с MODX, MIGX и Fenom: первичная разметка вёрстки и нарезка — его зона. После этого повседневное редактирование контента ложится на менеджера и не требует кода.

Атрибуты для разметки

Если работаете в IDE скопируйте себе на компьютер файл assets/components/migxpageconfigurator/css/mpc.css, тогда во время разметки IDE будет подсказывать какие атрибуты доступны.

Осторожно

у всех префикс data-mpc-

1. copy - используется совместно с атрибутом data-mpc-section, если нужно указать, что данная секция является копией секции в другом шаблоне; в качестве значения рекомендую указывать имя файла с оригинальной секцией
2. symbol - используется совместно с атрибутом data-mpc-snippet или data-mpc-parse, если его вызов должен состояться на этапе предварительного парсинга; принимает одно из двух значений { или ##; по умолчанию ##
3. cond - используется совместно с атрибутом data-mpc-item, если нужно выводить элементы поля типа Migx по условию; в значение принимает условие, в котором можно использовать переменные $i(№ итерации) или $l (№ номер последней итерации); при наличии вложенности Migx в Migx переменные будут иметь индексы соответствующие уровню вложенности. В условиях можно использовать только знаки сравнения закодированные функцией urlencode()
4. static - используется совместно с атрибутом data-mpc-section, если нужно указать, что данная секция является статической, т.е. одинаковой для всех страниц.
5. name - используется совместно с атрибутом data-mpc-section для задания человекопонятного названия секции.
6. item - указывается html-элементу, содержащему значения полей для заполнения конфигураций Migx, должен быть вложен в элемент data-mpc-field(тут возможен индекс)
7. unwrap - используется совместно с атрибутом data-mpc-chunk или data-mpc-item, указывает на то, что чанком является только содержимое, без оборачивающего тэга.
8. section - указывается html-элементу, который должен быть смысловой контентной секцией в конфигурации страницы.
9. snippet - указывается html-элементу, в котором должен быть расположен вызов сниппета; в качестве значения принимает строку вида SnippetName|presetName, где SnippetName - имя вызываемого сниппета, указанное так как вы указали бы его при вызове с помощью Fenom, presetName - ключ из массива параметров вызова.
10. chunk - указывается html-элементу, в который нужно вырезать в чанк; в качестве значения нужно указывать путь к чанку относительно папки с чанки из системных настроек.
11. include - используется совместно с атрибутом data-mpc-chunk, если нужно заменить его на конструкцию вида {include 'file:path/to/chunk'}
12. parse - используется совместно с атрибутом data-mpc-chunk, если нужно заменить его на конструкцию вида {$_modx->parseChunk('@FILE path/to/chunk', $params}; в качестве значения нужно передать массив параметров, например так data-mpc-parse="[$id => 1]".
13. remove - указывается html-элементу, который следует удалить из вёрстки после обработки, чаще всего это data-mpc-field или data-mpc-chunk для вложенных чанков.
14. attr - используется в тех случаях, когда необходимо указать динамические атрибуты, например <input type="checkbox" data-mpc-attr="{$checked}">.
15. field - используется для передачи значения из шаблона в админку; если html-элемент содержит атрибуты href или scr, т.е. являются ссылкой, фреймом или картинкой, значение будет взято из этих атрибутов, в противном случае значением будет всё содержимое элемента с атрибутом data-mpc-field.

Рендеринг

Чтобы не увеличивать время ответа сервера, конфигурации парсятся либо при запуске скрипта mgr_tpl.php, либо при сохранении ресурса. Под парсингом я понимаю замену плейсхолдеров их значениями, а сниппетов результатом их работы. Тут стоит отметить, что сниппеты могут срабатывать либо при отдаче на фронт, либо при предварительном парсинге.

Второй вариант не подходит для сниппетов, которые следует вызывать строго некэшированными, например для AjaxForm, mFilter2. При этом если сниппет не должен быть выполнен раньше, чем страница попадёт на фронт его вызов в файле секции будет начинаться с ##, ни в коем случае не стоит это исправлять. Править напрямую файлы секций вообще не стоит, вносите изменения через файл шаблона. То как будет записан вызов сниппета регулируется атрибутом data-mpc-symbol, по умолчанию, т.е. когда он не указан, вызов начинается с ##, если же вы указываете значение, то оно должно быть равным { или {, любое другое приведёт к ошибке. Обращаю ваше внимание, что бывают ситуации когда вам придётся использовать плейсхолдеры, доступ к которым есть только на фронте, такие плейсхолдеры следует записывать начиная с ##, т.е. вот так

##$placeholder}

Кеширование

Пока идёт разработка вам, вероятно, захочется, чтобы все изменения происходили сразу, для этого следует убедиться, что системная настройка mpc_dev_mode имеет значение Да тогда при каждом запуске скрипта mgr_tpl.php будет очищаться папка elements/parsed и кеш всего сайта. Так же очистить кеш можно из админки, через меню в шапке, помимо стандартного кеша, очиститься и кеш компонента. Если нет желания или возможности заходить в админку очистить кеш компонента, т.е. папку elements/parsed можно, запустив скрипт core/components/migxpageconfigurator/console/clear_cache.php.

Базовые понятия

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

Описание полей

Настройки секции

В базовом варианте, секция имеет следующие поля для настроек

• id - идентификатор секции, должен быть уникальным в пределах страницы, т.е. если добавляете две одинаковые секции они должны иметь разные id
• section_name - название секции, нужно для менеджера, чтобы ему было понятно какая это секция, а так же используется как ключ массива секций ресурса, т.е. в пределах ресурса должен быть уникальным, более того если название секции в ресурсе будет отличаться от названия секции в шаблонном ресурсе, то секция задвоится.
• file_name - путь файлу секции, нужен прежде всего для того, кто будет сопровождать проект после вас, чтобы он знал в каком файле лежит код секции, хотя лучше всего редактировать через файл шаблона и запуск скрипта
• hide_section - позволяет скрыть секцию на странице, не удаляя её полностью
• copy_from_origin - позволяет скопировать данные из оригинальной секции, которая хранится в одном из дочерних ресурсов ресурса Типы страниц
• is_static - если галочка установлена, контент для секции будет взят из ресурса Типы страниц, нужно для "сквозных" секций, т.е. для таких, которые могут быть на любой странице и всегда содержат одинаковую информацию
• position - определяет порядок секций на странице. Казалось бы зачем, если секции в таблице и порядок уже определён? Но тут стоит отметить, что если ресурсу задан шаблон и существует ресурс-шаблон, то даже при отсутствии заданных для текущего ресурса секций, на фронте будут выведены секции из шаблонного ресурса. А теперь давайте рассмотрим ситуацию, при которой на сайте есть страницы услуг, каждая страница состоит из 3-х секций: описание услуги (берётся из поля контент ресурса), стоимость услуги (берётся из секции) и форма обратной связи (статичная секция). В этом случае имеет смысл менять только секцию с ценами, т.е. шаблонный ресурс будет содержать 3 секции, а реальные страницы могут содержать только одну - с ценами. И если предположить, для какой-то из услуг нужно первой вывести секцию с формой. Для этого нужно в поле position указать значение -1 например, при условии, что ни в ресурсе Типы страниц, ни в ресурсе-шаблоне значение позиции не задано. Если же позиции заданы везде, то значение нужно поставить меньше имеющихся. Таким образом можно тасовать секции как угодно.

Содержимое секции

Посмотреть весь список доступных полей можно посмотреть в графическом интерфейсе компонента Migx, открыв на редактирование конфигурацию base. Часть полей также представляют собой конфигурации Migx, все они представлены здесь же, в графическом интерфейсе. К содержимому секции не имеют отношения конфигурации config, contacts и form_list.