Рассмотрим функциональность обработчиков событий применительно к Битрикс24.
Немного теории
Типовые места регистрации обработчиков событий в Bitrix Framework:
- local/php_interface/init.php;
- <module-root>/include.php;
- В базе данных при установке модуля.
Доработка Битрикс24, как правило, производится с помощью модулей. В репозиторий с кодом доработок не попадает вся публичная часть, а только конкретные модули.
Файл init.php, скорее всего, не будет контролироваться вашим кодом, а даже если и будет, то доработка Битрикс24 с использованием этого файла может привести к неприятным ошибкам.
Файл include.php внутри модуля исполняется только в момент подключения модуля (вызов \Bitrix\Main\Loader::includeModule). Если на странице модуль не подключается, то и обработчики выполнены не будут.
Регистрация ваших обработчиков
При доработке Битрикс24, самым надёжным и удобным способом подписки на глобальные события системы является регистрация ваших обработчиков в базе данных.
Основные классы для работы с Агентами:
| Класс | Назначение |
|---|---|
| \Bitrix\Main\EventManager | Менеджер событий. Предоставляет интерфейс регистрации, удаления и получения списка обработчиков. Основные методы:
|
| \Bitrix\Main\Event | Представляет само событие. Объединяет в себе информацию о событии: модуль, тип и параметры. Объекты данного класса приходят в функцию обработчик в качестве параметра при использовании событий “нового” типа. |
| \Bitrix\Main\EventResult | Результат выполнения события. Объект данного класса возвращается обработчиками событий “нового” типа. |
У классов \Bitrix\Main\Event и \Bitrix\Main\EventResult существует несколько наследников. Чаще всего вы встретитесь с \Bitrix\Main\ORM\Event и \Bitrix\Main\ORM\EventResult. Объекты этих классов используются при работе с событиями ORM.
Практика
Типовые задачи, решаемые с помощью обработчиков событий
- Отправка нестандартных оповещений на почту, в иные системы.
- С помощью кастомного JS/CSS кода добавить кнопку в карточке сделки.
- Запретить редактировать сущность crm, если не заполнено одно из полей.
- Отправка данных в стороннюю систему, при возникновении какого-то события, например: при создании сделки отправлять данные по ней в 1С.
- Синхронизация сущностей. Например, если обновилось поле в сделке, то обновляем поле в смарт-процессе.
Пример: запретим типовое действие по сделке
Запретить переводить сделку в одно из неуспешных состояний, если в таймлайне нет комментария от ответственного по сделке. Комментарий от ответственного должен быть последним.
Для решения необходимо:
- Проверить тип - успешный, неуспешный - можно с помощью класса \Bitrix\Crm\PhaseSemantics.
- Создать обработчик события OnBeforeCrmDealUpdate.
- Если статус сделки был изменён и стал неуспешным, то проверяем наличие комментария в таймлайне.
- Если последний комментарий в таймлайне был оставлен текущим ответственным по сделке, то завершаем выполнение обработчика.
- Если комментария нет или он был сделан другим пользователем, то откатываем статус до предыдущего и выводим пользователю сообщение с просьбой оставить комментарий.
- При изменении сделки внутри обработчика произойдёт рекурсия. Необходимо предусмотреть защиту от неё.
- Реализовать и выполнить миграцию.
Создание обработчика события
21 мин
Список ресурсов
Материалы для выполнения практики
- Исходный код примера (.zip)