claramente / claramente.options
Bitrix - Options
Package info
github.com/claramente-ru/bitrix-options
Type:bitrix-module
pkg:composer/claramente/claramente.options
Requires
- php: >=8.0
- composer/installers: ~1
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
⚠️ Обновление до 2.0.0: скрипты в опциях больше не поддерживаются. Перед обновлением перенесите скрипты (например, Яндекс Метрику) из опций в шаблон сайта. Теги
script,style,iframe,object,embed,noscriptудаляются вместе с содержимым при первом сохранении страницы параметров. Подробнее — в разделе HTML в текстовых опциях.
Установка через composer
Пример composer.json с установкой модуля в local/modules/
{
"extra": {
"installer-paths": {
"local/modules/{$name}/": ["type:bitrix-module"]
}
},
"require": {
"claramente/claramente.options": "^2.0"
}
}
-
Запустить
composer require claramente/claramente.options -
В административном разделе установить модуль claramente.options (/bitrix/admin/partner_modules.php?lang=ru)
-
Подключить модуль в
/local/php_interface/init.phpили в/bitrix/php_interface/init.phpдобавив строчкуCModule::IncludeModule('claramente.options') -
После установки модуля он будет доступен в разделе Контент => Параметры сайта (/bitrix/admin/claramente_options.php?lang=ru)
Использование модуля
- Получение значения опции для текущего языка:
cm_option(code, site_id) - Получение значения опции для всех языков:
cm_option_all_lang(code, site_id) - Установка нового значения опции:
cm_option_set(code, site_id, value) - Проверка существования опции для текущего языка:
cm_option_exists(code, site_id) - Проверка заполнения опции для текущего языка:
cm_option_filled(code, site_id)(значение"0"считается заполненным) - Удаление опции:
cm_option_delete(code, site_id)(файлы опции типа «Файл» удаляются вместе с ней)
cm_option_set() проверяет значение по правилам типа и при ошибке возвращает false.
Текст ошибки можно получить четвертым параметром:
if (! cm_option_set('price', null, '12,555', $error)) { echo $error; // Допускается не более 2 зн. после разделителя, округление не выполняется }
Для опции с отдельными значениями по языкам передается массив [['value' => ..., 'lang' => 'ru'], ...].
О модуле
Этот модуль упрощает работу с опциями сайта, позволяя редактировать контент и хранить важные данные, часто используемые в коде.
Аналог модуля COption из BX, но с расширенными возможностями: поддерживает удобное форматирование строк в административной панели, позволяет задавать тип данных, устанавливать ограничения и создавать новые типы. Модуль поддерживает возможность мультиязычности. Для каждой опции есть настройка - "Одно значение для всех языков", которое позволяет завести одно значение для всех языков или множество значений под конкретный язык.
В системе доступны несколько предустановленных типов данных:
- Строка
- Строки (множественный ввод, поддержка тысяч строк)
- Текст
- Число (целое или десятичное)
- Флаг (true/false)
- Дата
- Список
- Файл
Права доступа
- Страница параметров доступна всем, у кого есть доступ к модулю: можно менять и сохранять значения опций.
- Опции с отметкой «Только для администраторов» видят и меняют только администраторы.
- Создавать, редактировать и удалять параметры, настраивать вкладки может только администратор.
Тип «Число»
- Допускаются только цифры и один разделитель дробной части: точка или запятая. В базе хранится точка:
12,50сохраняется как12.5,007как7. - Любое другое значение (знаки
+и-, пробелы и разделители тысяч внутри числа,1e3, несколько разделителей) не сохраняется с ошибкой «Значение должно быть числом». - Точность (знаков после разделителя) задается в настройках параметра, от 0 до 10, по умолчанию 2. Точность 0 — только целые числа.
- Округления нет: значение с лишними знаками после разделителя не сохраняется.
- Не более 15 значащих цифр в целой и дробной части вместе.
cm_option()возвращаетintдля целых иfloatдля дробных чисел. Для вывода используйтеnumber_format():
echo number_format(cm_option('price'), 2, ',', ' ');
Если у параметра уменьшить точность или сменить тип на «Число», а текущее значение под новые правила не подходит, параметр не сохранится: значение нужно сначала исправить на странице параметров.
HTML в текстовых опциях
Значения типов «Строка», «Текст» и «Строки» сохраняются только с безопасным HTML (CBXSanitizer, уровень SECURE_LEVEL_LOW):
форматирование, div, span, ссылки (в том числе с rel), изображения, таблицы, атрибуты style, class, id.
Остальные теги удаляются, script, style, iframe, object, embed, noscript — вместе с содержимым.
Очистка выполняется для всех пользователей, включая администратора, и для cm_option_set().
- Значения без HTML (без символа
<) не меняются. - В значениях с HTML текст между тегами хранится закодированным (
&,"), в поле формы он показывается как введен. - Значение с HTML выводите в шаблоне без экранирования, иначе на сайте будут видны теги и сущности.
- Значение без HTML, которое выводится внутри атрибута, экранируйте:
<div title="<?= htmlspecialcharsbx(cm_option('promo')) ?>">. - Ограничения
CBXSanitizer: к адресу без схемы и без/в начале дописываетсяhttp://(page.html→http://page.html,/page.htmlне меняется), атрибутtitleс символами кроме букв, цифр и.?!,:;-удаляется,<br/>приводится к<br>.
Перед обновлением модуля перенесите скрипты (например, Яндекс Метрику) из опций в шаблон сайта. Уже сохраненные значения не меняются, но страница параметров при сохранении отправляет значения всех вкладок, поэтому скрипты во всех опциях удалятся при первом сохранении страницы.
В модуле существует возможность расставлять опции и сортировать их. Для переноса опций в группу необходимо создать новую вкладку. По умолчанию все опции хранятся во вкладке "Опции". После созданий новой вкладки можно создавать опции и помещать их туда, устанавливая сортировку.
Подсказки к параметрам
При создании или редактировании параметра заполните поле «Подсказка (текст без HTML)». На странице параметров сайта подсказка появится сразу после соответствующего поля. Для опции с отдельными значениями по языкам она выводится один раз после всего блока значений. Чтобы убрать подсказку, очистите поле и сохраните параметр.
Подсказка доступна для всех встроенных типов и пользовательских наследников AbstractOption.
HTML-теги показываются как текст, переводы строк сохраняются. Поддерживаются текстовые HTML-сущности,
например ,   и &. Исполняемая разметка не поддерживается.
В базе данных подсказка хранится в сериализованном массиве SETTINGS под ключом hint:
$settings = serialize([ 'hint' => 'Введите целое число от 1 до 10.', ]);
При программном изменении существующей опции добавляйте hint к ее настройкам, сохраняя остальные ключи.
Миграции Sprint переносят подсказку вместе с SETTINGS; изменение схемы БД не требуется.
Для опций без подсказки дополнительная строка формы не создается.
В общей административной форме вывод выполняет AbstractOption::getFormFieldHint().
Если собственная форма вызывает только getFormFieldValue() или getFormFieldMultipleValue(),
после поля отдельно вызовите getFormFieldHint() с теми же аргументами.
Сигнатуры методов типов, в том числе getFieldFooter(), сохранены.
Офлайн-проверки
Запустите из корня модуля:
php tests/run.php
Нужен только PHP CLI (8.0+) с mbstring. Bitrix не нужен: его API заменен заглушками, рабочая БД и сеть не используются. Предупреждения PHP во время проверок считаются ошибкой. Файл запускается только из CLI.
Структура:
tests/run.php— раннер: автозагрузка классов модуля,test(),assertSame(),assertTrue();tests/support/— заглушки Bitrix API и вспомогательные функции;tests/cases/— проверки по темам.
Проверки охватывают подсказки, миграции, права доступа, проверку токена сессии, экранирование вывода,
кэш и предзагрузчик, значения по языкам, типы данных (в том числе «Число»), очистку HTML,
удаление файлов и сохранение параметров и вкладок.
Они не заменяют проверку административных форм в установленном Bitrix: поведение настоящего CBXSanitizer и ORM проверяется на стенде.
Страница настроек параметров сайта
Страница настроек параметра
Оптимизация работы модуля
1. Кэширование SQL-запросов
Модуль поддерживает возможность кэширования SQL-запросов. Для кэширования отдельных запросов необходимо передать в cm_option последним параметром время кэширования в секундах.
Для включения глобального кэширования следует определить глобальную константу со временем кэша. Константа применяется, если время не передано или равно 0; явно переданное время приоритетнее:
const CLARAMENTE_OPTIONS_CACHE_TIME = 3600;
Обратите внимание, что константа должна быть объявлена до вызова метода cm_option.
2. Предварительная загрузка данных
Модуль поддерживает возможность загрузки всех опций сразу. Любой вызов метода cm_option сначала загружает все данные, после чего последующие запросы используют загруженные данные без дополнительных обращений к базе данных.
Для активации предварительной загрузки необходимо установить глобальную константу:
const CLARAMENTE_OPTIONS_PRELOADER = true;
После cm_option_set(), cm_option_delete() и сохранения параметров загруженные данные сбрасываются,
поэтому в том же хите cm_option() возвращает новое значение.
Обратите внимание, что константа должна быть объявлена до вызова метода cm_option.