Опции в MaxSite CMS

Для того, чтобы создать произвольную опцию, в MaxSite CMS, как правило, используется описательный подход, где не требуется программирование.

Опции задаются в ini-файлах, где каждая опция представляет собой секцию с предопределенными ключами. Обычно ini-файлы автоматически подключаются и отображаются в админ-панели. Главное условие — предопределенное расположение файлов.

В основном ini-файлы используются для создания/переопределения опций шаблонов. Также подобным образом задаются мета-опции записи — в них используется очень похожий вариант, хотя есть некоторые отличия.

Следует понимать, что ini-файлы опций представляют собой лишь надстройку над реальными php-функциями MaxSite CMS. Преимущество ini-файлов в том, что с их помощью достаточно просто управлять отображением опций в админ-панели. Например указывать тип input-поля (или textarea), добавлять описание, подсказки и т.п.

Общее описание опций

Любая опция состоит из двух параметров: ключ и тип. Если опции не существует, то при её использовании (получении) указывается значение по умолчанию.

Свои опции шаблона

Наиболее часто создают опции для шаблона. Для этого используется файл custom/my_options.ini. Этот файл определен так, что его опции будут выведены после «дефолтных» на странице Настройки шаблона.

При этом допускается размещать ini-файлы в каталоге шаблона options. Сами «дефолтные» опции расположены в shared/options/default/.

Опции компонентов

Опции компонентов размещаются в options.ini каждого компонента и автоматически подключаются в админ-панели. Они действуют точно также, как и любые другие опции.

Каталог шаблона options

Каталог options нужен для размещения в нём ini-файлов опций. Исторически так сложилось, что основные «дефолтные» опции переместились в shared-каталог, поэтому каталог шаблона options содержит только диспетчер опций — options.php.

Файл options/options.php можно переместить в custom/options.php (этот файл имеет более высокий приоритет). ^{В MaxSite CMS 102 и выше} Если в каталоге options нет ini-файлов, то его можно удалить.

Базовый синтаксис ini-опций

Используется стандартный для PHP обработчик ini-файлов. Значения ключей принятой заключать в двойные кавычки. Исключение можно сделать для английских одночных слов, цифр и некоторых других.

[Название сайта]
options_key = name_site
options_type = general
type = textfield
description = "Укажите название своего сайта"
default = ""

Если у опции не определён options_type, то он рассматривается как general. Для того, чтобы обеспечить уникальность опции в пределах каждого шаблона, принято указывать её тип совпадающий с каталогом шаблона. Для этого служит специальная замена %TEMPLATE%.

[Название сайта]
options_key = name_site
options_type = %TEMPLATE%
type = textfield
description = "Укажите название своего сайта"
default = ""

В ini-файлах можно использовать PHP-код, поэтому может встречаться подобная запись:

[Название сайта]
options_key = name_site
options_type = "<?php echo getinfo('template') ?>"
type = textfield
description = "Укажите название своего сайта"
default = ""

В некоторых сложных случаях PHP-функцию выносят отдельно и указывают её с помощью PHP_START ... PHP_END

[Первый блок шапки]
options_key = header_component1
options_type = %TEMPLATE%
type = select
description = "Выберите файл"
values = "PHP_START default_components PHP_END"

В данном примере будет выполнена функция default_components().

Секции

Для визуального разделения опций по вкладкам админ-панели используется указание начала секции.

[Соцсети]
options_key = social
options_type = templates
type = textarea
description = "Укажите иконки"
default = ""
section = "Соц.сети"
section_description = "Задайте иконки соцсетей для своего сайта"

Секция указывается только в первой её опции. Дальнейший вывод опций будет происходить в данной секции (вкладке), пока не будет встречена новая секция.

Чтобы вывести дополнительную «подсекцию» в виде заголовка, отделяющего опции используется subsection. Она может быть указана только со второй опции секции.

[Шаблон вывода записей]
...
subsection = "Вывод записей"

Типы полей опций

Для того, чтобы корректно вводить данные, поля опций могут иметь различный тип. Указывается это с помощью ключа «type». В зависимости от него, будет сформированы необходимые HTML-поля формы ввода.

Поддерживаются следующие варианты:

• textfield - текстовый input (с разными html-типами)
• select - выпадающий список
• checkbox - отметка
• radio - радиобоксы - выбор одного варианта из нескольких
• textarea - многострочное текстовое поле
• multicheckbox - несколько checkbox в одной опции. Результат опции - массив
• color - выбор цвета (используется jQuery-плагин)

Дополнительные параметры

Для textfield можно дополнительно указать textfield_type, который совпадает с типом поля HTML5. Например для ввода электронной почты используется «email».

[Ваш email]
options_key = myemail
options_type = %TEMPLATE%
type = textfield
textfield_type = email
default = ""

Для select, radio и multicheckbox используется поле values, где указывается список возможных значений через #.

type = select
values = "0.00 # 1.00 # 2.00"

Если же значение опции не совпадает с её названием, то используется дополнительный разделитель ||.

type = select
values = "0.00||Гринвич # 1.00||Варшава # 2.00||Киев"

Для textarea можно указать количество строк в rows. По умолчанию — 2.

Для radio и multicheckbox можно указать HTML-разделитель между боксами — параметр delimer.

Для типа textfield и textarea можно указать кавычку " в виде _QUOT_ (преобразуется в "). Это актуально для случаев, если нужно указать параметры HTML-тэгов.

Аналогичным образом произойдет замена _NBSP_ на пробел и _NR_ на перенос строки (в textarea).

Также для текстовых полей можно задать фоновую подсказку через параметр placeholder.

Для некоторых типов опций доступен параметр attr в котором можно задать HTML-атрибуты поля.

Переопределение опций

Для того, чтобы переопределить опцию нужно создать её с тем же именем и другими значениями.

Скрытие опций

Для скрытия опции достаточно определить её без параметров или без options_key.

[Название сайта]
[Краткое описание]

Скрытие опции не означает её удаления или обновления. Опция всё также будет доступна в базе данных и её всё также можно получить для использования.

Создание опции через функцию

Опцию можно создать (и обновить) с помощью функции mso_add_option('ключ', 'значение', 'тип')

Получение опций

Для получения опции используется функция mso_get_option('ключ', 'тип', 'дефолт').

Удаление опции

Для удаления опции из базы данных используется функция mso_delete_option('ключ', 'тип').