События настроек модуля

[OnBeforeAllOptionsBuild] Событие для создания своих табов в настройках модуля

Событие позволяет добавить собственные вкладки и опции в настройки модуля стандартным механизмом Битрикс. Добавленные настройки не пропадут после обновления модуля.

Изменено в версии 3.9.0: ответы нескольких обработчиков сливаются

Раньше, если на событие были подписаны две доработки, на странице оставалась вкладка только последнего обработчика, а первое же сохранение настроек стирало опции пропавшей вкладки. Теперь модуль сводит ответы всех обработчиков:

• arAllOptions сливается по ключу вкладки: новый ключ добавляется, существующий заменяется ответом обработчика целиком, ключ, которого нет в ответе, остаётся как был;
• aTabs сливается по DIV: вкладка с новым DIV дописывается в конец, с уже известным — заменяет прежнюю на её месте;
• обработчики вызываются по одному, и каждый следующий получает в параметрах набор, уже собранный предыдущими, — поэтому обработчик, дописывающий поле в чужую вкладку, видит её. На старом ядре, где вызвать обработчики по одному нельзя, событие отправляется разом: все обработчики видят исходный набор, а сливаются только их ответы;
• assetsFile учитывается у каждого обработчика, а не только у последнего.

Существующие обработчики, написанные по примерам ниже, работают без изменений. Учитываются только ответы с типом EventResult::SUCCESS.

Описание события

Параметры события

Параметр	Тип	Описание
arAllOptions	array	Массив всех опций модуля, сгруппированных по вкладкам
aTabs	array	Массив вкладок настроек модуля
isSaveHit	bool	Флаг: является ли текущий запрос сохранением настроек

Возвращаемое значение

Верните EventResult::SUCCESS с массивом, содержащим arAllOptions и aTabs. Опционально можно передать assetsFile -- путь к PHP-файлу, который будет подключен на странице настроек. Файл подключается, только если он существует и имеет расширение .php; файлы всех обработчиков подключаются по очереди после того, как отработали все обработчики.

Исключение из обработчика модуль не перехватывает: страница настроек остановится на нём.

return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
    'arAllOptions' => $arAllOptions,
    'aTabs' => $aTabs,
    // 'assetsFile' => '/path/to/custom_assets.php' // опционально
]);

Пример вызова события

//файл /bitrix/php_interface/init.php

//подписываемся на событие
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'rbs.moyskladstocks',
    'OnBeforeAllOptionsBuild',
    'OnBeforeAllOptionsBuildHandler'
);

function OnBeforeAllOptionsBuildHandler(\Bitrix\Main\Event $event)
{
    //получаем параметры события
    $eventParams = $event->getParameters();

    //массив всех опций модуля
    // $arAllOptions — ассоциативный массив, ключ = ID таба
    // [
    //     'tab_name' => [
    //         'Заголовок группы опций',
    //         ['option_code', 'Название опции', 'значение_по_умолчанию', ['тип_поля', 'доп_параметры']],
    //         // ...
    //     ],
    //     // ... другие вкладки
    // ];
    $arAllOptions = $eventParams['arAllOptions'];

    //массив вкладок для работы опций
    // $aTabs — массив вкладок
    // [
    //     [
    //         'DIV' => 'tab_div_name',
    //         'TAB' => 'Название вкладки',
    //         'ICON' => 'icon_name',
    //         'TITLE' => 'Заголовок вкладки'
    //     ],
    //     // ... другие вкладки
    // ];
    $aTabs = $eventParams['aTabs'];

    //Пример добавления кастомных опций
    //Далее стандартным способом для битриксовых модулей добавляем табы и параметры
    $arAllOptions['custom_tab'][] = 'Custom tab';
    $arAllOptions['custom_tab'][] = ["custom_option", "Custom option", '', ['checkbox', "N"]];

    $aTabs[] = [
        "DIV" => "custom_tab",
        "TAB" => 'Custom tab',
        "ICON" => "custom_tab",
        "TITLE" => 'Custom tab'
    ];

    //$result оставляем всегда таким перед возвращением результата события
    $result = [
        'arAllOptions' => $arAllOptions,
        'aTabs' => $aTabs
    ];

    //возвращаем SUCCESS если нужно поменять массив опций
    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, $result);
}

Результат работы события:

Примеры использования

Добавление таба с разными типами опций

Пример добавления кастомной вкладки с несколькими типами опций: текстовое поле, чекбокс, выпадающий список и мультиселект.

function OnBeforeAllOptionsBuildHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();
    $arAllOptions = $eventParams['arAllOptions'];
    $aTabs = $eventParams['aTabs'];

    // Заголовок секции
    $arAllOptions['my_integration'][] = 'Настройки интеграции';

    // Текстовое поле (тип text, ширина 50 символов)
    $arAllOptions['my_integration'][] = [
        'my_integration_api_url',
        'URL внешнего API',
        'https://api.example.com',
        ['text', 50]
    ];

    // Чекбокс
    $arAllOptions['my_integration'][] = [
        'my_integration_enabled',
        'Включить интеграцию',
        'N',
        ['checkbox', 'N']
    ];

    // Выпадающий список (selectbox)
    $arAllOptions['my_integration'][] = [
        'my_integration_mode',
        'Режим работы',
        'sync',
        ['selectbox', [
            'sync' => 'Синхронный',
            'async' => 'Асинхронный',
            'manual' => 'Ручной',
        ]]
    ];

    // Мультиселект (multiselectbox)
    $arAllOptions['my_integration'][] = [
        'my_integration_entities',
        'Сущности для синхронизации',
        '',
        ['multiselectbox', [
            'products' => 'Товары',
            'orders' => 'Заказы',
            'customers' => 'Контрагенты',
            'stocks' => 'Остатки',
        ]]
    ];

    // Регистрируем вкладку
    $aTabs[] = [
        'DIV' => 'my_integration',
        'TAB' => 'Моя интеграция',
        'ICON' => 'main_settings',
        'TITLE' => 'Настройки кастомной интеграции',
    ];

    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
        'arAllOptions' => $arAllOptions,
        'aTabs' => $aTabs,
    ]);
}

---

[OnBeforeWebHookOptionsBuild] Событие для вывода веб-хуков в соответствующей вкладке

Событие позволяет зарегистрировать в МойСклад подписки на веб-хуки по дополнительным сущностям. Оно только создаёт подписки на вкладке «Веб-хуки»: обрабатывать такие веб-хуки модуль не будет — см. предупреждение ниже.

Исключение из обработчика модуль ловит и пишет в лог; ответы остальных обработчиков учитываются.

Описание события

Параметры события

Событие не передает параметров (пустой массив).

Возвращаемое значение

Верните EventResult::SUCCESS с массивом формата:

return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
    'result' => [
        'entity_type' => ['ACTION_1', 'ACTION_2', ...]
    ]
]);

Где entity_type -- тип сущности МС (move, supply, purchaseorder, demand и др.), а массив действий -- одно или несколько из: CREATE, UPDATE, DELETE.

Тип сущности — только строчные латинские буквы. Сущность с другим ключом или со значением не массивом, а также действие вне CREATE, UPDATE, DELETE отбрасываются молча.

Событие только подписывает, но не обрабатывает

Сам модуль сущности вне своих шести типов не обрабатывает: веб-хук по такой сущности придёт, модуль запишет о нём строку в лог — и на этом всё. Чтобы принимать веб-хуки своим кодом, объявите сущность в реестре событием OnBuildWebhookEntityList (с версии 3.9.0). Реестр сам создаёт подписку, так что OnBeforeWebHookOptionsBuild для такой сущности уже не нужен.

Слияние списков — с версии 3.9.0

Списки всех обработчиков объединяются со списком модуля и реестра: действия одной сущности складываются, а не заменяются. В более ранних версиях ответ склеивался через array_merge, и сущность из ответа перетирала действия штатной.

Пример вызова события

//файл /bitrix/php_interface/init.php

//подписываемся на событие
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'rbs.moyskladstocks',
    'OnBeforeWebHookOptionsBuild',
    'OnBeforeWebHookOptionsBuildHandler'
);

function OnBeforeWebHookOptionsBuildHandler(\Bitrix\Main\Event $event)
{
    //возвращаем массив такого вида:
    // 'result' => [...] - у массива единственный ключ - result,
    // внутри result идет массив такой структуры:
    // 'entity' => ['UPDATE', 'CREATE', ...],
    // где 'entity' - сущность в МС, на которое подписываем веб-хук
    // массив у ключа сущности это три событя веб-хука 'UPDATE', 'CREATE', 'DELETE'

    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
        'result' => [
            'move' => ['CREATE', 'UPDATE'],
            'supply' => ['UPDATE', 'DELETE'],
            'purchaseorder' => ['CREATE'],
            'demand' => ['UPDATE']
        ]
    ]);
}

В результате работы события во вкладке «Веб-хуки» появятся новые подписки с подписью «Обслуживает: подписка из OnBeforeWebHookOptionsBuild». Обработчик приёма для них объявляется отдельно — в OnBuildWebhookEntityList.

Примеры использования

Подписка на складские операции

Добавление веб-хуков для отслеживания перемещений, приёмок и заказов поставщикам — для автоматического обновления остатков при изменении складских документов.

function OnBeforeWebHookOptionsBuildHandler(\Bitrix\Main\Event $event)
{
    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
        'result' => [
            // Перемещения — отслеживаем создание и обновление
            'move' => ['CREATE', 'UPDATE'],
            // Приёмки — отслеживаем все действия
            'supply' => ['CREATE', 'UPDATE', 'DELETE'],
            // Заказы поставщикам — отслеживаем создание и обновление
            'purchaseorder' => ['CREATE', 'UPDATE'],
        ]
    ]);
}

---

[OnCollectPersistentOptions] Опции, которые переживают сохранение настроек

Доступно с версии 3.9.0

На более ранних версиях событие не вызывается.

Сохранение настроек модуля начинается с удаления всех его опций, после чего записываются только те, что выведены полями на вкладках. Всё остальное — служебное состояние вашей доработки, отсечки, флаги — пропадает при первом же нажатии «Сохранить», на какой бы вкладке его ни нажали.

Событие позволяет назвать опции, которые модуль должен сохранить и вернуть на место после сохранения настроек.

Исключение из обработчика модуль не перехватывает: оно обрывает сохранение настроек ещё до того, как модуль удалит опции.

Состояние агентов модуль сохраняет сам

Начиная с версии 3.9.0 служебные опции агентов (ag_{id}_offset, ag_{id}_last, ag_{id}_last_full, ag_{id}_tag, ag_{id}_full_once, ag_{id}_pass_start) переживают сохранение без всякого обработчика — и у штатных агентов, и у агентов, зарегистрированных через OnBuildAgentList, вместе с их собственными опциями из options. Событие нужно для остальных опций.

Описание события

Параметры события

Событие не передаёт параметров.

Возвращаемое значение

EventResult::SUCCESS с ключом options — списком имён опций модуля:

return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
    'options' => ['my_last_sync', 'my_queue_state'],
]);

Правила

• Имя опции — латиница, цифры, _; остальные имена отбрасываются.
• Опция, выведенная полем на какой-либо вкладке, не восстанавливается: значение, которое пользователь только что ввёл в форму, важнее прежнего.
• Пустые значения не сохраняются — после «Сохранить» такая опция останется пустой.
• Учитываются только ответы с типом EventResult::SUCCESS.

Пример вызова события

//файл /bitrix/php_interface/init.php

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'rbs.moyskladstocks',
    'OnCollectPersistentOptions',
    'OnCollectPersistentOptionsHandler'
);

function OnCollectPersistentOptionsHandler(\Bitrix\Main\Event $event)
{
    // опции, которые доработка пишет через \Rbs\MoyskladStocks\Config::setOption()
    // и не выводит полями на вкладках
    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
        'options' => [
            'my_consignment_last_sync',
            'my_consignment_full_pass',
        ],
    ]);
}

---

[OnBuildCustomProcessList] Свой разовый процесс на странице настроек

Событие регистрирует собственные разовые процессы — страницы, которые открываются с кнопки «Начать разовый импорт» в настройках модуля. Кнопку для своего процесса выводит ваш код на своей вкладке:

\Rbs\MoyskladStocks\Internals\OptionUtils::buildImportOnceButton($arAllOptions['my_tab'], 'my_full_import');

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

Исключение из обработчика модуль не перехватывает: страница настроек остановится на нём. Если одно имя процесса зарегистрировали несколько обработчиков, берётся первый непустой file.

Изменено в версии 3.9.0: файл процесса может лежать вне модуля

Раньше файл процесса искался только по пути /bitrix/modules/rbs.moyskladstocks/options/custom/process/{имя}.php — внутри модуля, где его затирало обновление. Теперь в событии можно передать путь к файлу в своём коде. Прежняя форма — просто имя процесса — работает как раньше.

Описание события

Параметры события

Событие не передаёт параметров.

Возвращаемое значение

EventResult::SUCCESS с ключом result — списком процессов. Элемент списка — либо имя процесса строкой, либо массив с именем и файлом:

return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
    'result' => [
        'my_old_process', // файл внутри модуля: options/custom/process/my_old_process.php
        [
            'name' => 'my_full_import',
            'file' => '/local/php_interface/my_module/process/full_import.php', // с 3.9.0
        ],
    ],
]);

Правила

• Имя процесса — только латиница и _, без цифр; остальные имена отбрасываются.
• file — путь от корня сайта. Он принимается, только если файл существует, имеет расширение .php и лежит внутри корня сайта. Иначе модуль ищет файл по прежнему пути внутри модуля.
• Имя, совпадающее со штатным разовым процессом модуля, кнопкой ведёт на штатный процесс.

Пример вызова события

//файл /bitrix/php_interface/init.php

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'rbs.moyskladstocks',
    'OnBuildCustomProcessList',
    'OnBuildCustomProcessListHandler'
);

function OnBuildCustomProcessListHandler(\Bitrix\Main\Event $event)
{
    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, [
        'result' => [
            [
                'name' => 'my_full_import',
                'file' => '/local/php_interface/my_module/process/full_import.php',
            ],
        ],
    ]);
}