home chevron_right
Компоненты sf.wizard и sf.wizard.stage

sf.wizard — каркас пошагового мастера: контейнер, навигация, управление состоянием шаговlink

sf.wizard — основной компонент, который запускает мастер по конфигурационному файлу и собирает “сессию” мастера: описание, список шагов (actions), текущее состояние и накопленные данные. В реализации компонент рассчитан на работу из админского сценария: при отсутствии прав администратора выполнение прерывается (то есть мастер из коробки предназначен для служебных задач — упаковка/установка/настройка решения, миграции и т.п.).

Ключевой вход для компонента — это путь к директории мастера и путь к файлу конфигурации. После загрузки конфигурации компонент нормализует ключи массива (приводит к единому регистру), берёт описание мастера (DESCRIPTION) и список шагов (ACTION), а текущее состояние подтягивает из хранилища данных (чтобы можно было продолжать мастер, переходить по шагам и передавать данные между этапами).

Навигация по шагам организована через параметр запроса stage (номер шага). В шаблоне мастера формируется макет и кнопки “назад/вперёд”, а обновление текущего шага делается через AJAX-подгрузку содержимого шага в контейнер (без перезагрузки всей страницы). Дополнительно поддерживается логика “условных шагов”: если в описании шага задано условие, компонент может пропускать шаги, пока условие не выполнено.

Параметры, которые важно понимать при встраивании:

  • WIZARD_DIR и WIZARD_CONFIG_FILE — технически “скрытые” параметры компонента (в типовом использовании вы задаёте их прямо в вызове компонента).
  • AJAX_TIME_STEP и AJAX_TIME_INTERVAL — параметры для пошагового/итеративного выполнения (внутри шага действие может выполняться многократно). В реализации есть ограничение сверху (не больше 20 секунд). Если параметры не переданы корректно, используются значения по умолчанию.

Пример подключения мастера на служебной странице:

<?php

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$APPLICATION->IncludeComponent(
    'simai:sf.wizard',
    '.default',
    [
        'WIZARD_DIR' => '/wizard',
        'WIZARD_CONFIG_FILE' => '/wizard/.wizard.config.php',

        // опционально: тонкая настройка “пошагового” выполнения
        'AJAX_TIME_INTERVAL' => 1,
        'AJAX_TIME_STEP' => 10,

        'AJAX_MODE' => 'Y',
        'AJAX_OPTION_JUMP' => 'N',
        'AJAX_OPTION_STYLE' => 'N',
        'AJAX_OPTION_HISTORY' => 'N',
        'AJAX_OPTION_ADDITIONAL' => '',
        'COMPOSITE_FRAME_MODE' => 'N',
        'CACHE_TYPE' => 'N',
    ],
    false
);

sf.wizard.stage — отрисовка/логика отдельного шага; выполняет actions и показывает форму/результатыlink

sf.wizard.stage — компонент “этапа” (шага). Его задача — взять из хранилища состояние мастера по коду мастера, подготовить данные текущего шага и передать управление конкретному действию (action), которое отвечает за бизнес-логику шага.

Ключевой параметр этапа — WIZARD_CODE: это код, по которому в хранилище лежит состояние мастера (описание, текущий шаг, массив данных и текущая конфигурация действия). В штатной схеме вы не вызываете sf.wizard.stage вручную — он вызывается из шаблона sf.wizard, вместе с AJAX-параметрами, чтобы обновлять только область шага.

В шаблоне этапа подключается файл действия (action) через require. Это важный архитектурный момент: action — это не “класс” и не “обработчик события”, а готовый PHP-скрипт, который получает доступ к массиву $arResult мастера и может:

  • вывести форму/прогресс/результат шага,
  • обработать ввод,
  • обновить данные мастера,
  • управлять статусом шага (например, переводить шаг в “в работе” или “успешно завершён”).

Минимальный ориентир по данным, с которыми работает action (это именно контракт массива, который компонент готовит для шага): CONFIG, WIZARD, STAGE, ACTION, DATA, а также ACTION.INPUT / ACTION.OUTPUT.

Пример “скелета” action-файла (идея — показать подход, а не навязать единственную реализацию):

<?php

declare(strict_types=1);

use SIMAI\Main\Configuration\Property;

if (!isset($arResult['WIZARD']['CODE'], $arResult['STAGE'], $arResult['ACTION'])) {
    return;
}

// Читаем входные данные шага (если они настроены через DATA_INPUT_CODE)
$input = $arResult['ACTION']['INPUT'] ?? [];

// ... выполняем работу шага ...

// Пишем результат (на практике часто пишут в $arResult['DATA'][...] и/или ACTION.OUTPUT)
$arResult['ACTION']['OUTPUT'] = [
    'result' => 'ok',
];

// Обновляем статус шага (пример)
$arResult['STAGE']['STATUS'] = 'SUCCESS';

// Сохраняем обновлённое состояние мастера в хранилище
Property::setArray($arResult['WIZARD']['CODE'], $arResult);

// Вывод результата шага (если нужно)
echo '<div class="sf-alert sf-alert-success">Шаг выполнен</div>';

Использование: шаги мастера связываются с actions из /simai/wizard/action; данные/шаблоны шагов можно расширятьlink

Связка “шаг → action” строится через конфигурацию мастера: каждый шаг в массиве ACTION имеет CODE, и по этому коду подбирается файл action.php. Важная деталь реализации: сначала компонент пытается найти действие внутри директории конкретного мастера (это позволяет упаковать кастомные действия вместе с мастером), и только если там файла нет — берётся системное действие из каталога /simai/wizard/action/<code>/action.php. За счёт этого расширение обычно делается без правки ядра: вы добавляете действие в папку мастера и используете его код в конфиге.

Передача данных между шагами устроена через “хранилище данных” мастера и массив DATA. Для шага можно задавать:

  • откуда брать вход: DATA_INPUT_CODE (например, setup → $arResult['DATA']['setup'])
  • куда класть выход: DATA_OUTPUT_CODE (например, result → $arResult['DATA']['result'])

Это делает шаги переиспользуемыми: одно и то же действие можно применять в разных мастерах, меняя только коды входа/выхода и параметры.