Search by

claramente / claramente.options

claramente

Bitrix - Options

Package info

github.com/claramente-ru/bitrix-options

Type:bitrix-module

pkg:composer/claramente/claramente.options

Statistics

Installs: 1 691

Dependents: 0

Suggesters: 0

Stars: 2

Open Issues: 0

2.0.0 2026-11-14 15:54 UTC

This package is auto-updated.

Last update: 2026-11-14 15:57:02 UTC


README

Claramente

⚠️ Обновление до 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"
  }
}
  1. Запустить composer require claramente/claramente.options

  2. В административном разделе установить модуль claramente.options (/bitrix/admin/partner_modules.php?lang=ru)

  3. Подключить модуль в /local/php_interface/init.php или в /bitrix/php_interface/init.php добавив строчку CModule::IncludeModule('claramente.options')

  4. После установки модуля он будет доступен в разделе Контент => Параметры сайта (/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 текст между тегами хранится закодированным (&amp;, &quot;), в поле формы он показывается как введен.
  • Значение с HTML выводите в шаблоне без экранирования, иначе на сайте будут видны теги и сущности.
  • Значение без HTML, которое выводится внутри атрибута, экранируйте: <div title="<?= htmlspecialcharsbx(cm_option('promo')) ?>">.
  • Ограничения CBXSanitizer: к адресу без схемы и без / в начале дописывается http:// (page.html → http://page.html, /page.html не меняется), атрибут title с символами кроме букв, цифр и .?!,:;- удаляется, <br/> приводится к <br>.

Перед обновлением модуля перенесите скрипты (например, Яндекс Метрику) из опций в шаблон сайта. Уже сохраненные значения не меняются, но страница параметров при сохранении отправляет значения всех вкладок, поэтому скрипты во всех опциях удалятся при первом сохранении страницы.

В модуле существует возможность расставлять опции и сортировать их. Для переноса опций в группу необходимо создать новую вкладку. По умолчанию все опции хранятся во вкладке "Опции". После созданий новой вкладки можно создавать опции и помещать их туда, устанавливая сортировку.

Подсказки к параметрам

При создании или редактировании параметра заполните поле «Подсказка (текст без HTML)». На странице параметров сайта подсказка появится сразу после соответствующего поля. Для опции с отдельными значениями по языкам она выводится один раз после всего блока значений. Чтобы убрать подсказку, очистите поле и сохраните параметр.

Подсказка доступна для всех встроенных типов и пользовательских наследников AbstractOption. HTML-теги показываются как текст, переводы строк сохраняются. Поддерживаются текстовые HTML-сущности, например &nbsp;, &#160; и &amp;. Исполняемая разметка не поддерживается.

В базе данных подсказка хранится в сериализованном массиве 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.