1С-Битрикс: кастомная страница настроек темы через Option API
Задача: сделать свою страницу настроек темы и сохранить параметры так, чтобы они стабильно применялись в шаблоне сайта. В новой документации Битрикс для этой задачи есть все базовые элементы: работа с административной панелью, API опций модуля и стандартная защита формы от CSRF.
Официальные источники:
- https://docs.1c-bitrix.ru/pages/cms-basics/admin-panel.html
- https://docs.1c-bitrix.ru/pages/security/csrf-ssrf.html#csrf-tokeny
- https://docs.1c-bitrix.ru/api/classes/Bitrix-Main-Config-Option.html#method\_set
- https://docs.1c-bitrix.ru/api/classes/Bitrix-Main-Config-Option.html#method\_get
- https://docs.1c-bitrix.ru/api/classes/CAllMain.html#method\_AddPanelButton
- https://docs.1c-bitrix.ru/api/classes/CAllMain.html#method\_GetPopupLink
В чем проблема
Частая ситуация: параметры темы хранят в файлах или случайных таблицах, а затем сложно понять, где именно меняется цвет, телефон, логотип или поведение блока. В итоге:
- нет единой точки хранения;
- настройки меняются небезопасно;
- после обновлений или миграций часть параметров теряется;
- сложно проверить, что именно применилось на фронте.
Для устойчивой схемы в Битрикс достаточно:
- хранить настройки в
Option; - отправлять форму только с CSRF-токеном;
- читать настройки в шаблоне сайта в одном месте.
Рабочее решение
Ниже минимальный рабочий сценарий без недокументированных зависимостей.
Шаг 1. Добавляем кнопку открытия страницы настройки
Документация по панели администрирования показывает, что можно добавить свою кнопку через AddPanelButton.
<?php
// Например, в шаблоне после подключения пролога
$APPLICATION->AddPanelButton([
"ID" => "theme_settings",
"TEXT" => "Настройки темы",
"TYPE" => "BIG",
"SORT" => 100,
"HREF" => "/local/admin/theme_settings.php",
]);
API:
- https://docs.1c-bitrix.ru/api/classes/CAllMain.html#method\_AddPanelButton
- https://docs.1c-bitrix.ru/pages/cms-basics/admin-panel.html#dobavit-knopki
Если хотите открыть страницу в popup, используйте GetPopupLink:
https://docs.1c-bitrix.ru/api/classes/CAllMain.html#method\_GetPopupLink
Шаг 2. Делаем форму с CSRF-токеном
В новой документации по безопасности явно указаны bitrixsessidpost() и checkbitrixsessid().
<?php
require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/modules/main/include/prolog_admin_before.php");
use Bitrix\Main\Config\Option;
$moduleId = "main";
if ($_SERVER["REQUEST_METHOD"] === "POST") {
if (!check_bitrix_sessid()) {
die("Invalid session");
}
$phone = trim((string)($_POST["theme_phone"] ?? ""));
$accent = trim((string)($_POST["theme_accent"] ?? ""));
Option::set($moduleId, "theme_phone", $phone);
Option::set($moduleId, "theme_accent", $accent);
}
$savedPhone = Option::get($moduleId, "theme_phone", "");
$savedAccent = Option::get($moduleId, "theme_accent", "#0a7c66");
?>
<form method="post">
<?= bitrix_sessid_post(); ?>
<label>Телефон в шапке</label><br>
<input type="text" name="theme_phone" value="<?= htmlspecialchars($savedPhone, ENT_QUOTES, "UTF-8"); ?>"><br><br>
<label>Акцентный цвет</label><br>
<input type="text" name="theme_accent" value="<?= htmlspecialchars($savedAccent, ENT_QUOTES, "UTF-8"); ?>"><br><br>
<button type="submit">Сохранить</button>
</form>
Документация:
- https://docs.1c-bitrix.ru/pages/security/csrf-ssrf.html#csrf-tokeny
- https://docs.1c-bitrix.ru/api/classes/Bitrix-Main-Config-Option.html#method\_set
- https://docs.1c-bitrix.ru/api/classes/Bitrix-Main-Config-Option.html#method\_get
Шаг 3. Читаем настройки в шаблоне темы
Дальше используем те же ключи Option в шаблоне:
<?php
use Bitrix\Main\Config\Option;
$moduleId = "main";
$themePhone = Option::get($moduleId, "theme_phone", "+7 (000) 000-00-00");
$themeAccent = Option::get($moduleId, "theme_accent", "#0a7c66");
?>
<style>
:root { --theme-accent: <?= htmlspecialchars($themeAccent, ENT_QUOTES, "UTF-8"); ?>; }
</style>
<a href="tel:<?= htmlspecialchars($themePhone, ENT_QUOTES, "UTF-8"); ?>">
<?= htmlspecialchars($themePhone, ENT_QUOTES, "UTF-8"); ?>
</a>
Идея простая: одна точка сохранения и одна точка чтения. Это упрощает поддержку и перенос.
Проверка результата
Проверяем по шагам:
- Открыть страницу настроек через кнопку панели.
- Сохранить значения.
- Обновить публичную страницу и убедиться, что новые данные применились.
Быстрая проверка из HTML:
curl -s https://example.ru/ | grep -E "theme-accent|tel:"
Ожидаемый признак: в ответе видны обновленные значения цвета и телефона.
Типичные ошибки
❌ Ошибка: сохраняют POST без проверки токена.
Причина: нет checkbitrixsessid().
Как исправить: добавить проверку и bitrixsessidpost() в форму.
❌ Ошибка: ключи в Option::set() и Option::get() не совпадают.
Причина: опечатки вроде themephone vs themetel.
Как исправить: вынести ключи в константы или использовать одинаковые литералы.
❌ Ошибка: выводят значение без экранирования.
Причина: прямой вывод пользовательского текста в HTML.
Как исправить: использовать htmlspecialchars(..., ENT_QUOTES, "UTF-8").
❌ Ошибка: ожидают, что кнопка панели появится для всех пользователей.
Причина: права и настройки панели зависят от пользователя/группы.
Как исправить: проверить доступы и настройки панели администрирования:
https://docs.1c-bitrix.ru/pages/cms-basics/admin-panel.html
Где применять
- В темах, где нужно управлять контактами, цветами и переключателями блоков.
- В проектах с контент-редакторами, которым нужен простой интерфейс без правок кода.
- В production, где важно централизованное хранение параметров.
Дополнительно по структуре проекта:
- https://viku-lov.ru/blog/bitrix-local-folder-project-structure
- https://viku-lov.ru/blog/bitrix-simple-module-with-component
SOCIAL SHARE CARD GENERATOR