Как вывести ошибку с HTML-разметкой при обновлении сделки в Битрикс24

При работе со сделками в Битрикс24 иногда возникает необходимость прервать операцию обновления и показать пользователю кастомное сообщение об ошибке. Стандартный механизм валидации позволяет выводить простой текст, но что делать, если в сообщении требуется разместить ссылку или другую HTML-разметку?

Стандартный подход и его ограничения

Обычно для проверки условий при обновлении элемента используется обработчик события, подключенный в init.php. Например, чтобы запретить изменение сделок с ID больше 100, можно использовать следующий код:

public static function handleElementChange(&$arFields): bool
{
    if ($arFields['ID'] > 100) {
        global $APPLICATION;
        $APPLICATION->ThrowException('Текст ошибки!');
        return false;
    }
    return true;
}

Основное ограничение этого метода - невозможность вывода форматированного сообщения. Метод ThrowException принимает только строку, которая будет отображена как обычный текст. HTML-теги экранируются и не интерпретируются.

Решение: вывод ошибки с HTML-вёрсткой

Чтобы обойти это ограничение и вывести сообщение со ссылкой или другим форматированием, можно использовать следующий алгоритм:

1. Отключить стандартное отображение ошибки. Не вызывайте $APPLICATION->ThrowException() для основного сообщения.
2. Записать HTML-сообщение в отдельное поле результата. Используйте поле RESULT_MESSAGE массива $arFields, чтобы передать готовую HTML-разметку.
3. Инициировать ошибку пустым исключением. Вызовите ThrowException() с пустой строкой, чтобы триггернуть статус ошибки, но не перезаписать ваше форматированное сообщение.

Пример реализации

Вот как будет выглядеть модифицированный обработчик для вывода ошибки с кликабельной ссылкой:

public static function handleElementChange(&$arFields): bool
{
    if ($arFields['ID'] > 100) {
        global $APPLICATION;
        
        // Формируем HTML-сообщение со ссылкой
        $errorHtml = 'Операция запрещена. <a href="/custom/page.php" target="_blank">Перейти к инструкции</a>';
        
        // Передаём HTML в поле RESULT_MESSAGE
        $arFields['RESULT_MESSAGE'] = $errorHtml;
        
        // Инициируем ошибку (пустое сообщение не перезапишет RESULT_MESSAGE)
        $APPLICATION->ThrowException('');
        
        return false;
    }
    return true;
}

Ключевые моменты

• Поле RESULT_MESSAGE имеет приоритет при отображении. Если оно заполнено, система покажет его содержимое вместо строки из ThrowException.
• Вызов ThrowException('') обязателен для перевода операции в состояние «ошибка».
• Убедитесь, что ваша HTML-разметка безопасна и корректно экранирована, чтобы избежать уязвимостей.

Данный подход позволяет гибко кастомизировать сообщения об ошибках, делая их более информативными и удобными для пользователя.