Поля формы

Поля формы представлены разными типами, для каждого из которых имеются свои методы объявления. Рассмотрим наиболее часто используемые типы полей.

Текстовое поле однострочное

Поле ввода однострочного текста <input type="text">. Для этого используйте метод text(field_name, field_title, default_value, is_lang).

$form
    ->text(
        'author',                 # атрибут "name" поля формы
        $this->langAdmin('Имя'),  # заголовок поля
        '',                       # значение по умолчанию
        true                      # использовать мультиязычность для поля
    )
    ->required($this->langAdmin('Введите имя автора'));

Для всех типов текстовых полей рекомендуется использовать мультиязычность контента. Обратим внимание что, в таком случае данные из формы приходят в виде строки json и требуется поле в таблице БД типа TEXT или дополнительная таблица в БД, отвечающая за мультиязычность.

Метод ->required() позволяет отметить поле как обязательное к заполнению и установить текст сообщения в случае сохранения формы с пустым полем.

Текстовое поле многострочное

Для поля ввода многострочного текста <textarea> предусмотрен одноименный метод textarea(field_name, field_title, default_value, is_lang, opts).

$form
    ->textarea(
        'short_description',                  # атрибут "name" поля формы
        $this->langAdmin('Краткое описание'), # заголовок поля
        '',                                   # значение по умолчанию
        true                                  # использовать мультиязычность для поля
    )
   ->tip($this->langAdmin('Дополнительное уточнение (подсказка)'));

Метод ->tip() позволяет задать подсказку, выводится как небольшой popup при наведении на символ ?, возле заголовка поля.

Флаг (отметка)

Для поля флаг (отметка) <input type="checkbox">, предусмотрен одноименный метод checkbox(field_name, field_title, is_checked, opts)

$form
    ->checkbox(
        'enabled',                     # атрибут "name" поля формы
        $this->langAdmin('Выключено'), # заголовок поля
        true                           # значение атрибута `checked` 
    )
    ->label($this->langAdmin('Текст справа от поля'));

Метод ->label() позволяет задать уточнение для поля, выводится непосредственно возле поля, с правой стороны.

Группа отметок

Список флажков (checkbox list), реализует одноименный метод checkboxList(field_name, field_title, callback, is_rotate)

$form
   ->checkboxList(
       'list_1',                     # атрибут "name" поля формы
       $this->langAdmin('Список_1'), # заголовок поля
       null,                         # callback списка флажков
       true                          # возможность ротации (перемещения) элементов списка
   )
   ->option('key_1', 'Title 1', false)
   ->option('key_2', 'Title 2', false)
   ->option('key_3', 'Title 3', true)
   ->option('key_4', 'Title 4', true)
   ->option('key_5', 'Title 5', true)

   ->checkboxList(
       'list_2', 
       $this->langAdmin('Список_2'), 
       function () {
           return [
               ['id' => 1, 'title' => 'Title 1'],
               ['id' => 2, 'title' => 'Title 2', 'checked' => true],
           ];
       }
   );

Список флажков может добавляться как при помощи метода option(key, title, checked) или формироваться при помощи callback в методе checkboxList, возвращая массив в формате:

[
    ['id' => $id_1, 'title' => $title_1], 
    ['id' => $id_2, 'title' => $title_2 'checked' => true], 
    ...
]

Также доступна ротация элементов списка, ее устанавливает четвертый параметр метода checkboxList

Число

Числовое поле <input type="number">, для этого типа предусмотрен одноименный метод number(field_name, field_title, min, max, step, default, opt).

$form->number(
    'percent',                    # атрибут "name" поля формы
    $this->langAdmin('Процент') , # название поля
    0,                            # минимально допустимое числовое значение
    100                           # максимально допустимое числовое значение (0 - без ограничения)
);

Поле переключатель (radio)

Для поля переключатель <input type="radio"> используем метод radio(field_name, field_title, optionsCallback, opts)

$form
   ->radio(
       'post_visible',                         # атрибут "name" поля формы
       $this->langAdmin('Доступ к публикации') # заголовок поля
   )
   ->option(
       '1',                                    # атрибут "value"
       $this->langAdmin('Да')                  # заголовок 
    )
   ->option('2', $this->langAdmin('Нет'))
   ->option('3', $this->langAdmin('Возможно'));

Обязательно необходимо задать возможные варианты выбора option(radio_value_key, label_title).

Выпадающий список (select)

Выпадающий список формируется посредством метода
select(field_name, field_title, default_id, callback_options, callback_empty_option)

$form->select(
    'cat_id',                       # атрибут "name" поля формы
    $this->langAdmin('Категория'),  # заголовок поля
    false,                          # ID выбранного по умолчанию элемента   
    function() {                    # callback получения элементов выпадающего списка в формате [$id => ['id' => $id, 'title' => $title]]
        $data = $this->model->categoriesListing();
        return \func::array_transparent($data, 'id', true);
    }, 
    function() use(& $form) {       # callback функция, вызываемая перед отрисовкой, в примере применяется для задания текста выбора из списка  
        return $form->recordID() ? false : $this->langAdmin('Выбрать'); 
    }
);

В примере не используем default_id (можно передать cat_id по умолчанию), чтоб показать как задается дополнительный элемент списка. Обратим внимание на callback получения элементов выпадающего списка, он может возвращать массив в формате [$id => ['id' => $id, 'title' => $title]], или строку HTML с уже сформированными элементами поля options.
При интеграции компонента формы в список, при редактировании записи из списка, доступен метод recordID(), позволяющий получить id текущей записи, для задания элемента по умолчанию.

Рассмотрим такой пример:

$form->select('cat_id', $this->langAdmin('Категория'), false, function($field) use(& $form) {
   $data = $this->model->categoriesListing();
   $result = [];
   if ( ! $form->recordID()) {
       $result[] = '<option value="0">' . $this->langAdmin('Выбрать') . '</option>';
   }
   $val = $field->value();
   foreach ($data as $v) {
       $result[] = '<option value="' . $v['id'] . '"' . ($val == $v['id'] ? ' selected="selected"' : '') . '>' . $v['title'] . '</option>';
   }
   return join('', $result);
});

Параметром callback для получения элементов выпадающего списка является объект текущего поля $field, дает возможность получить значение value для текущего поля, в данном случае cat_id идентификатор категории записи.
Таким образом можем установить атрибут selected для выбранной ранее категории, при редактировании записи.

Поле выбора даты

Поле выбора даты задается при помощи метода datepicker(field_name, field_title, default).

$form->datepicker(
    'created',                           # атрибут "name" поля формы
    $this->langAdmin('Дата публикации'), # заголовок поля
    $this->db->now()                     # значение по умолчанию
)->required($this->langAdmin('Задайте дату публикации');

Изображения

Загрузка изображений выполняется при помощи метода
images(field_name, field_title, count, maxSize, sizes).

$form->images(
    'post_images',                   # атрибут "name" поля формы
    $this->langAdmin('Изображения'), # заголовок поля
    5                                # максимальное количество изображений
);

Также в параметрах можно задать максимальный размер загружаемых изображений в байтах (по умолчанию 4Мб на один файл), и массив с размерами (по умолчанию изображения сохраняются в двух размерах 's' => ['width' => 100, 'height' => 100] и 'o' - оригинальный размер изображения).
Обратим внимание что, данные из формы приходят в виде строки json и требуется поле в таблице БД типа TEXT.

Для того чтоб получить URL первого сохраненного из всех изображений для вывода например в списке можно использовать метод getImageURL(imgs_json, size).

$list
   ->column('main_img', $this->langAdmin('Главное изображение'), 150, [
       'type' => $list::COLUMN_TYPE_CUSTOM,
   ], function($value, $item, $opts){
       return !empty($item['main_img'])? '<img style="width:50px" src="' . Form::getImageURL($item['main_img'], 's') . '">': '';
   });

Для получения пути ко всем загруженным изображениям используем метод Form::getImagesPath($item['main_img'], 's').

Файлы

Загрузка файлов аналогична загрузке изображений, используем метод
files(field_name, field_title, count, maxSize, public, extensions)

$form->files(
    'documents',                   # атрибут "name" поля формы
    $this->langAdmin('Документы'), # заголовок поля
    2                              # максимальное количество изображений
);

Для получения url всех загруженных файлов применяется метод getFilesURL($item['documents']).

Статический текст

Предусмотрены так называемые служебные поля формы, к ним относится возможность вывода статического текста - значения поля без тега . Реализуется методом staticText(field_name, field_title, content).

$form->staticText(
    'status',
    $this->langAdmin('Название')
);

В форме редактирования записи в статический текст будет выведено содержимое по ключу 'status'.

Разделитель

К служебным элементам формы также относится разделитель divider(content, align). Параметрами является контент, по умолчанию - это тег <hr />, и признак по какому краю формы выравнивать разделитель.

Полнотекстовый редактор (WYSIWYG)

В качестве поля формы предусмотрено использование текстового редактора wysiwyg(field_name, field_title, default, is_lang, width, height) или wysiwygFCK(field_name, field_title, default, is_lang, width, height). Также в качестве параметров доступно задание высоты, ширины окна редактора и другие визуальные настройки.
Рекомендуем также использовать мультиязычность. Обратите внимание что в таком случае данные из формы приходят в виде строки JSON и для хранения в таблице базы данных столбец должен быть типа TEXT или подобный.

$form->wysiwyg('post_content_1', $this->langAdmin('Содержание публикации'));
$form->wysiwygFCK('post_content_2', $this->langAdmin('Содержание публикации'));

Компоненты

В формах также доступно использование специальных полей: поля с автоподбором (autocomplete), теги, конструктор контента Publicator и динамические свойства. Такие поля позволяют значительно расширить функционал разрабарываемых сущностей и удобство использования форм. Читайте о них в статье "Компоненты"