MigxPageConfigurator

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

1. Выносим общий html в файл-обёртку.
2. Остальной html разбирается на файлы-шаблоны.
3. Каждый файл-шаблон и файл-обёртка размечаются специальными атрибутами (см. ниже).
4. Запускается скрипт, для обёртки - slice_tpl.php, для файлов-шаблонов - mgr_tpl.php.
5. При необходимости можно скриптом mgr_elems.php создать элементы сайта: плагины, сниппеты, TV, ресурсы.

Из дополнительных возможностей стоит отметить:

• Встроенный lazy-load с обрезкой изображений.
• Управление формами из админки.

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

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

Осторожно

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

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

Рендеринг

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

Второй вариант не подходит для сниппетов, которые следует вызывать строго некэшированными, например для AjaxForm, AjaxFormItLogin, 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 - путь файлу секции, нужен прежде всего для того, кто будет сопровождать проект после вас, чтобы он знал в каком файле лежит код секции, хотя лучше всего редактировать через файл шаблона и запуск скрипта
• pt-lg, pb-lg, pt, pb - эти настройки оставил лично для себя, потому что предпочитаю задавать интервал между секциями именно внутренними отступами, и при перемещении секций может возникнуть необходимость эти интервалы скорректировать
• hide_section - позволяет скрыть секцию на странице, не удаляя её полностью
• copy_from_origin - позволяет скопировать данные из оригинальной секции, которая хранится в одном из дочерних ресурсов ресурса Типы страниц
• is_static - если галочка установлена, контент для секции будет взят из ресурса Типы страниц, нужно для "сквозных" секций, т.е. для таких, которые могут быть на любой странице и всегда содержат одинаковую информацию
• position - определяет порядок секций на странице. Казалось бы зачем, если секции в таблице и порядок уже определён? Но тут стоит отметить, что если ресурсу задан шаблон и существует ресурс-шаблон, то даже при отсутствии заданных для текущего ресурса секций, на фронте будут выведены секции из шаблонного ресурса. А теперь давайте рассмотрим ситуацию, при которой на сайте есть страницы услуг, каждая страница состоит из 3-х секций: описание услуги (берётся из поля контент ресурса), стоимость услуги (берётся из секции) и форма обратной связи (статичная секция). В этом случае имеет смысл менять только секцию с ценами, т.е. шаблонный ресурс будет содержать 3 секции, а реальные страницы могут содержать только одну - с ценами. И если предположить, для какой-то из услуг нужно первой вывести секцию с формой. Для этого нужно в поле position указать значение -1 например, при условии, что ни в ресурсе Типы страниц, ни в ресурсе-шаблоне значение позиции не задано. Если же позиции заданы везде, то значение нужно поставить меньше имеющихся. Таким образом можно тасовать секции как угодно.

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

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