Настройки дополнения
Простые настройки дополнения
Под простыми настройками понимается форма настроек дополнения в панели управления, поля в которую добавляются посредством объявления их в методе init дополнения.
Указываются они в форме массива следующим образом:
$this->configSettings(array(
'key1' => array( // Уникальный ключ настройки, допустимые символы: a-z, A-Z, 0-9, -, _
'title' => 'Название поля отображаемое в форме',
'title.description' => 'Описание поля отображаемое под названием поля в виде серого текста уменьшенного размера',
'description' => 'Дополнительное описание отображаемое под полем',
'tip' => 'Всплывающая подсказка в виде иконки-вопроса возле названия поля или справа от поля (в случае поля ввода числа)',
'placeholder' => 'Пример значения для текстовых полей ввода (text, textarea, password)',
'input' => 'Тип поля: text, textarea и т.п. Все доступные типы полей описаны ниже',
'type' => 'Тип данных: TYPE_STR, TYPE_BOOL, ... Возможно указать тип отличный от типа по умолчанию',
'default' => 'Значение по умолчанию, должно соответствовать типу данных поля, для избежания ошибок с приведением типов',
'required' => true/false, // Обязательное поле, по умолчанию - false
'readonly' => true/false, // Поле доступно только для чтения, без возможности изменить в нем значение указываемое в настройке "default", по умолчанию - false
'onChange' => function($newValue, $oldValue){
// Функция выполняющая выполнить дополнительную валидацию указываемого пользователем значения.
// Применимо ко всем типам полей, предполагающих выбор / ввод значения пользователем.
// Пример проверки нового значения:
// if (empty($newValue)) {
// $this->errors->set('Ошибка при проверке нового значения');
// return false;
// }
return $newValue; // Возвращает итоговое значение настройки или false в случае ошибки
},
),
'key2' => array(
// ...
),
));
В дополнении к указанным настройкам у поля также могут быть специфичные дополнительные настройки, смотрите пример их объявления в настройках каждого типа.
В дальнейшем обращение к данным настройкам, а вернее получение значений указанных в форме, возможно при помощи метода $this->config, например:
$value1 = $this->config('key1');
Также доступен метод $this->configUpdate выполняющий изменение значения настройки и его сохранение:
$this->configUpdate('key1', 'value');
Текстовые поля
Поле ввода текста:
array(
'text1' => array(
'title' => 'Однострочный текст',
'input' => 'text',
//'width' => 100, // Ширина поля в пикселях (100, '100px', '50%'), по умолчанию на всю ширину
),
'text2' => array(
'title' => 'Многострочный текст',
'input' => 'textarea',
),
);
Тип данных по умолчанию - TYPE_STR.
По умолчанию текстовые поля являются мультиязычными и при включении нескольких языков в проекте возможно указать значение для каждого из языков, отключить это можно указав 'lang' => false,.
При получении значения также можно указать требуемую версию языка:
$text1 = $this->config('text1');
$text1_ru = $this->config('text1', '', 'ru');
Флаг (отметка)
Поле отметки (да/нет).
array(
'key' => array(
'title' => 'Название',
'description' => 'Описание отображаемое справа от отметки',
'input' => 'checkbox',
),
);
Тип данных по умолчанию - TYPE_BOOL.
Группа отметок
Группа отметок да/нет для выбора нескольких значений.
array(
'key' => array(
'title' => 'Название',
'input' => 'checkbox-group',
'options' => array(
1 => array('title' => 'Отметка №1'),
2 => array('title' => 'Отметка №2'),
//...
),
),
);
Тип данных по умолчанию - TYPE_ARRAY, для приведения к нужному типу используйте TYPE_ARRAY_, например TYPE_ARRAY_UINT.
Сохраненные данные возвращаются ($this->config()) в виде массива.
Выпадающий список (select)
Поле для выбора одного значения из списка доступных.
array(
'key' => array(
'title' => 'Название',
'input' => 'select',
'options' => array( // Также здесь может быть функция (callback) возвращающая массив схожей структуры
'1' => array('title' => 'Вариант №1'),
'2' => array('title' => 'Вариант №2', 'description' => 'Дополнительное описание, отображаемое в случае если вариант выбран'),
//...
),
),
);
Тип данных по умолчанию - TYPE_STR.
Пароль (password)
Поле для ввода пароля.
array(
'key' => array(
'title' => 'Название',
'input' => 'password',
),
);
Тип данных по умолчанию - TYPE_NOTRIM (строка без обработки). Значение хранится в зашифрованном виде и не отображается при редактировании.
Также при необходимости можно принудительно шифровать значение любого из полей указав в настройках поля 'encrypt' => true,
Число
Поле для ввода числа.
array(
'key' => array(
'title' => 'Название',
'input' => 'number',
'min' => 5, // Минимально допустимое значение
'max' => 100, // Максимально допустимое значение
'tip' => $this->lang('мин'), // Пример краткого описания, например единицы в которых указывается значение
),
);
Тип данных по умолчанию - TYPE_UINT (беззнаковое целое).
Настройка tip будет отображаться справа от поля в случае если текст не длиннее 15 символов.
Изображение
Поле для загрузки файлов изображений.
Допустимые расширения: jpg, jpeg, gif, png, svg
array(
'image1' => array(
'title' => 'Название',
'input' => 'image',
'image' => array(
'sizes' => array(
'small' => array(
'width' => 100, 'height' => false,
'vertical' => array('width' => false, 'height' => 100)
),
'view' => array(
'width' => 800, 'height' => false,
'vertical' => array('width' => false, 'height' => 800)
),
),
//'maxSize' => 10485760, # Максимально допустимый размер файла изображения в байтах
'limit' => 1, # Максимально доступное кол-во загружаемых файлов изображений
),
),
);
В поле sizes указываются все необходимые изображения в которых будет сохранено исходное загружаемое изображение.
Текстовый ключ размера должен быть уникальным и указываться латиницей, допустимые символы: a-z, A-Z, 0-9, -, _
Для получения URL загруженного файла изображения используйте метод $this->configImages:
$url = $this->configImages('image1', 'small'); // Вторым параметром указывается ключ требуемого размера
// В случае если в настройке limit указано значение 2 и более метод вернет список URL требуемого размера
Файл
Поле для загрузки одного файла.
Допустимые расширения по умолчанию: jpg,jpeg,gif,png,bmp,tiff,ico,odt,doc,docx,docm,xls,xlsx,xlsm,ppt,rtf,pdf,djvu,zip,gzip,gz,7z,rar,txt,xml
array(
'file1' => array(
'title' => 'Название',
'input' => 'file',
'file' => array(
// Дополнительные настройки:
//'extensionsAllowed' => 'png,svg,ico',
//'maxSize' => 3145728, // максимально допустимый размер загружаемого файла в байтах
//'publicStore' => true/false, // true - после загрузки файлы доступны по прямой ссылке (URL)
),
),
);
Для получения URL загруженного файла используйте метод $this->configFiles:
$url = $this->configFiles('file1');
В случае если загружаемый файл не должен быть доступен по прямой ссылке после загрузки, можно изменить директорию хранения на /files/extensions/ следующим образом:
'file' => array(
'publicStore' => false,
),
Дополнительные типы полей
Скрытое поле
Поле не отображаемое в форме, но значение которого может быть указано/изменено в дополнении.
Зачастую необходимо для данных формируемых в процессе установки, получаемых из внешних источников.
array(
'key' => array(
'title' => 'Название',
'input' => 'hidden',
),
);
Тип данных по умолчанию - TYPE_STR.
Разделитель
Поле разделящее поля горизонтальной полосой <hr />.
Зачастую необходимо для данных формируемых в процессе установки, получаемых из внешних источников.
array(
'key' => array(
'input' => 'divider',
),
);
Тип данных по умолчанию - TYPE_STR.
Ключ поля при этом может быть указан например D1, D2.
Заголовок
Поле-заголовок для группы полей.
array(
'key' => array(
'title' => 'Заголовок',
'input' => 'title',
),
);
Тип данных по умолчанию - TYPE_STR.
Ключ поля при этом может быть указан например D1, D2.
Табы настроек
В случае если настроек много и необходимо разделить их на несколько табов сделать это можно следующим образом:
$this->configSettings(array(
'key1' => array(
'title' => 'Поле №1',
'input' => 'text',
'tab' => 'tabKey1', // ключ таба 1
),
'key2' => array(
'title' => 'Поле №2',
'input' => 'text',
'tab' => 'tabKey2', // ключ таба 2
),
), array(
'tabs' => array(
'tabKey1' => array( // Уникальный ключ таба, допустимые символы: a-z, A-Z, 0-9, -, _
'title' => 'Таб №1',
),
'tabKey2' => array(
'title' => 'Таб №2',
),
),
));
В примере настройка key1 будет отображаться в табе №1, а настройка key2 в табе №2.
Видимость полей
Простые поля формы могут быть взаимосвязаны между собой посредством настроек видимости, например следующим образом:
array(
'key1' => array(
'title' => '№1',
'input' => 'checkbox',
),
'key2' => array(
'title' => '№2',
'input' => 'checkbox',
'visibleIf' => ['key1' => true],
),
'key3' => array(
'title' => '№3',
'input' => 'checkbox',
'hiddenIf' => ['key1' => true, 'key2' => true],
),
);
В примере поле №2 будет отображаться только если было отмечено поле №1,
а поле №3 будет скрыто если было отмечена одно из полей №1 или №2.
В параметре hiddenIf/visibleIf указывается список полей в формате 'ключ поля'=>'значение поля'.
Настройки и компонент Формы
Более сложные настройки дополнения могут формироваться на основе компонента Формы.
Сделать это можно в методе init() дополнения следующим образом:
/** @var \bff\extend\extension\settings\Form */
public $settings;
public function init()
{
parent::init();
$this->settings = $this->configSettingsForm($this->langAdmin('Настройки'));
$this->settings->tab('tab1', $this->langAdmin('Основные настройки'));
$this->settings->text('title', $this->langAdmin('Заголовок'));
$this->settings->checkbox('enabled', $this->langAdmin('Выключено'));
$this->configSettings(array(
// ...
));
}
Обратите внимание что вызов метода configSettings также обязателен и должен выполняться после вызова configSettingsForm.
О всех доступных типах полей форм читайте в статье "Поля формы".