Создание и обновление элементов

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

В актуальной версии через манифесты управляются:

ресурсы — команда resources apply (дерево страниц, их поля, TV и группы);
плагины — команда plugins apply (код плагина и его привязка к системным событиям).

TV, сниппеты, чанки и шаблоны

Их не нужно создавать командами с этой страницы: TV, шаблоны и чанки заводит сама нарезка из размеченной вёрстки, а файловые сниппеты в админке создавать не требуется. Подробнее — в разделе «TV, сниппеты, чанки и шаблоны» ниже.

Как запускается

Команды выполняются из консоли через обёртку console/mpc (см. Консольные команды (CLI)):

./console/mpc <группа> apply [файл|имя] [флаги]

Где взять манифест: компонент сам находит файл по группе. Путь к базе манифестов определяется в таком порядке приоритета:

переменная окружения MPC_MANIFESTS_PATH;
системная настройка mpc_manifests_path;
дефолт components/migxpageconfigurator/console/manifests/ (относительно папки core/).

Аргумент после apply необязателен:

Вызов	Какой файл применится
`resources apply`	`{база}/resources.php` (по имени группы)
`resources apply prod`	`{база}/prod.php` (профиль/окружение)
`resources apply ./my/tree.php`	указанный файл напрямую

Имя без расширения дополняется .php. Существующий файл по абсолютному или относительному пути берётся как есть, минуя базу.

Сначала --dry-run

Перед боевым запуском прогоните команду с флагом --dry-run — она покажет план (что будет создано / обновлено / пропущено), ничего не записывая. Это особенно важно для плагинов, где набор событий перезаписывается целиком.

Готовые шаблоны манифестов лежат в console/examples/ (resources.example.php, plugins.example.php и др.).

Ресурсы

Команда resources apply создаёт и обновляет дерево ресурсов. Манифест — массив с ключами context (контекст, по умолчанию web) и resources (список узлов-ресурсов).

Простейший пример

Один ресурс:

php

<?php
return [
    'context' => 'web',
    'resources' => [
        [
            'pagetitle' => 'Главная',
            'template'  => 'base',
            'published' => 1,
        ],
    ],
];

Применяем:

./console/mpc resources apply

Вывод (пример):

План: создать 1, обновить 0, без изменений 0

Запустите ту же команду ещё раз — ресурс уже существует и не изменился, поэтому:

Готово: создать 0, обновить 0, без изменений 1

То есть манифест можно безопасно прогонять сколько угодно раз — повторный запуск не плодит дубли.

Поля узла-ресурса

Узел — это массив полей ресурса. Из специальных:

pagetitle — обязателен. По нему (вместе с контекстом) ищется существующий ресурс, поэтому держите pagetitle уникальным в пределах контекста.
alias — если не задан, генерируется из pagetitle автоматически.
template — шаблон именем или id. Имя ищется по названию шаблона (templatename); если шаблон с таким именем не найден, подставится 0.

Остальные ключи передаются ресурсу как есть — published, hidemenu, menuindex, content, introtext, parent и любые другие поля modResource.

Если поле не указано, применяются разумные значения по умолчанию:

Поле	Значение по умолчанию
`published`	`true`
`hidemenu`	`false`
`deleted`	`false`
`richtext`	`false`
`searchable`	`true`
`uri_override`	`false`
`isfolder`	`true`, если у узла есть дети, иначе `false`

Поля context_key, parent, alias, uri и menuindex вычисляются автоматически из положения узла в дереве — задавать их вручную не нужно.

Переменные шаблона (TV) и группы

Значения TV для ресурса задаются в ключе tvs, членство в группах ресурсов — в ключе groups:

php

return [
    'context' => 'web',
    'resources' => [
        [
            'pagetitle' => 'Услуга — печати',
            'template'  => 'base',
            'published' => 1,
            'tvs' => [
                'img'    => 'assets/images/pechati.png',
                'is_hit' => 1,
            ],
            'groups' => ['Closed'],
        ],
    ],
];

Информация

tvs и groups — это значения для ресурса, а не описание самих TV или групп. Сами TV должны уже существовать (заведены в админке или пришли с пакетом).

Дерево ресурсов

Дочерние ресурсы описываются в ключе children (или resources — для совместимости со старым форматом). Вложенность любой глубины; parent, uri и menuindex детей считаются автоматически:

php

return [
    'context' => 'web',
    'resources' => [
        [
            'pagetitle' => 'Главная',
            'alias'     => 'home',
            'template'  => 'base',
            'published' => 1,
            'children'  => [
                [
                    'pagetitle' => 'О компании',
                    'alias'     => 'about',
                    'template'  => 'base',
                    'published' => 1,
                ],
                [
                    'pagetitle' => 'Услуги',
                    'alias'     => 'services',
                    'isfolder'  => 1,
                    'published' => 1,
                    'children'  => [
                        ['pagetitle' => 'Консалтинг', 'alias' => 'consulting', 'published' => 1],
                    ],
                ],
            ],
        ],
    ],
];

menuindex проставляется по порядку следования узлов в массиве (0, 1, 2…) в пределах одного родителя.

Что обновляется, а что нет

Ресурс ищется по паре context_key + pagetitle:

нашёлся и отличается от манифеста — обновляются перечисленные поля и TV (update);
нашёлся и совпадает — пропускается (skip);
не нашёлся — создаётся (create).

Ресурсы, которых нет в манифесте, не удаляются — команда только создаёт и обновляет, но ничего не сносит. Поля createdon, editedon, publishedon и uri при сравнении не учитываются (MODX управляет ими сам), поэтому они не вызывают ложных «обновлений».

После сохранения ресурса компонент наследует ему конфигурацию его типа страницы (copyConfig) — так же, как при обычном создании ресурса-страницы.

Точечное применение — `--only`

Чтобы применить из манифеста только один ресурс (а не всё дерево), укажите флаг --only со значением pagetitle, alias или контекст:uri:

./console/mpc resources apply --only=services
./console/mpc resources apply --only="О компании"

Остальные узлы будут пропущены; родители при этом по-прежнему используются для расчёта дерева.

Плагины

Команда plugins apply создаёт/обновляет плагины и синхронизирует их привязку к системным событиям. Манифест — массив, где ключ — имя плагина.

Полная форма: плагин + события

php

<?php
return [
    'MyPlugin' => [
        'file'         => 'plugin.myplugin',  // core/elements/plugins/plugin.myplugin.php
        'description'  => 'Описание плагина',
        'categoryName' => 'Мои плагины',       // опц.: категория создастся, если её нет
        'static'       => 1,                   // опц.: привязка к файлу-исходнику
        'events'       => [
            'OnDocFormSave',
            'OnLoadWebDocument',
        ],
    ],
];

Применяем:

./console/mpc plugins apply

Поля:

file — путь к коду плагина относительно core/elements/plugins/, без расширения .php. Если задан, плагин создаётся/обновляется.
description — описание.
categoryName — категория; создаётся автоматически, если её ещё нет.
static — если 1, плагин привязан к файлу-исходнику (статический элемент).
events — список системных событий, к которым привязывается плагин.

Короткая форма: только синхронизация событий

Если плагин уже существует и нужно лишь поправить его события, достаточно перечислить их массивом:

php

return [
    'ExistingPlugin' => [
        'OnDocFormDelete',
        'OnHandleRequest',
    ],
];

Важно: `events` — это полный желаемый набор

Набор событий приводится ровно к указанному: недостающие привязки добавляются, лишние отвязываются. То есть если у плагина в админке есть событие, которого нет в манифесте, после применения он от него отвяжется.

Внимание

Из-за этого перед боевым запуском plugins apply обязательно прогоняйте --dry-run и проверяйте план. Плагины, не упомянутые в манифесте, при этом не затрагиваются.

TV, сниппеты, чанки и шаблоны

Эти элементы не нужно создавать отдельной командой — о них заботится сама нарезка:

TV заводятся из разметки. Поля, размеченные data-mpc-tv, нарезка создаёт как переменные шаблона (modTemplateVar) и сама привязывает к нужному шаблону — см. Разметка вёрстки и Нарезка.
Шаблоны создаёт нарезка. Из служебного заголовка файла-шаблона (с именем шаблона) компонент создаёт или обновляет сам шаблон MODX (modTemplate) и связанный с ним ресурс-тип страницы.
Чанки создаёт нарезка. Блоки, размеченные data-mpc-chunk, вырезаются в файлы чанков — отдельно их заводить не надо (см. Работа с чанками).
Сниппеты — файловые: их код лежит в файлах и вызывается без записи в админке (pdoTools умеет файловые сниппеты), поэтому отдельно «создавать» сниппет тоже не требуется — см. Работа со сниппетами.

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

Старый скрипт mgr_elems.php

В ранних версиях TV, сниппеты и плагины можно было заводить скриптом console/mgr_elems.php <тип> с файлами tv.inc.php / snippet.inc.php / plugin.inc.php. В актуальной версии он ретайрнут: ресурсы перешли на resources apply, плагины — на plugins apply, а TV, шаблоны и чанки создаёт нарезка.

Связь с нарезкой

Создание ресурса через resources apply не запускает нарезку автоматически — оно лишь заводит/обновляет сам ресурс и наследует ему конфиг типа. Нарезка вёрстки в файлы секций и чанки выполняется отдельно — см. Нарезка.

handyShop

Утилиты

Настройки

Утилиты

События

Backend API