Конструктор форм

Используя конструктор форм вы минимизируете дублирование кода и ускорите разработку форм модулей и дополнений в админ-панели.

Форма состоит из:

заголовка формы
полей формы
табов, разделяющих поля формы на логические группы полей
кнопок управления формой

Всем этим позволяет управлять компонент Form. Для инициализации объекта формы воспользуйтесь методом tplAdmin::form(). Рассмотрим простой пример создания формы.

Простая форма

В качестве примера возьмем упрощенную сущность публикаций, представленную в базе данных следующим образом:

CREATE TABLE `bff_posts` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT, -- ID публикации
  `title` varchar(200) NOT NULL DEFAULT '', -- заголовок публикации
  `content` TEXT, -- текст публикации
  `enabled` tinyint(1) unsigned NOT NULL DEFAULT '1', -- включена ли публикации
  `created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, -- дата создания публикации
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Для формирования формы можно выделить несколько логических шагов:

Cоздаем объект компонента форм $form которому передаем объект контроллера.

$list = \tplAdmin::form($this);

На практике в форме может быть большее количество полей, в таком случае её объявление (добавление полей) можно вынести в отдельный шаблон путем указания второго параметра и названия файла шаблона в нем:

// php файл шаблона контроллера /tpl/admin.post.form.php
$list = \tplAdmin::form($this, 'admin.post.form');

В шаблоне будет также доступен объект формы $form и объект контроллера $this.

Указываем заголовок формы:

$form->setTitle('Публикации / Управление');

Создаем таб $form->tab(tab_key, tab_title) с параметрами ключ(уникальное название латиницей) и указываем его название, после чего добавляем к нему поля формы.
Полей в форме может быть большое количество, их можно разделить на несколько табов. После объявления таба, добавляем поля, которые будут вложены непосредственно в этот таб.

$form->tab('tab1', 'Таб #1');
    // добавляем поля...
$form->tab('tab2', 'Таб #2');
    // добавляем поля...

Добавляем поля формы различных типов:
- текстовое поле - text(field_name, field_title, default_value, lang)
  - field_name - атрибут name поля, он должен совпадать с названием поля в базе данных
  - field_title - название поля в форме
  - default_value - значение поля по умолчанию
  - lang - является ли поле мультиязычным (подробнее об этом будет ниже)
- многострочное текстовое поле - textarea(field_name, field_title, default_value, lang)
- поле checkbox - checkbox(field_name, field_title, default_value)
- поле выбора даты - datepicker(field_name, field_title)
- Подробнее о работе с различными типами полей формы можно узнать из статьи "Поля формы"
Добавляем кнопку отправки формы $form->buttonSubmit(title, callback), параметрами являются название кнопки и callback обработчик события отправки формы.
В примере мы используем обработчик по умолчанию (onSave).

$form->buttonSubmit('Отправить');

Обрабатываем событие сохранение формы

$form->onSave(function($id, $data){
    # вызываем метод модели контроллера для сохранения данных записи по ee $id
    # данные в формате ['field_name' => 'field_value']
    return $this->model->postSave($id, $data);
});

В обработчик события сохранения формы передаем callback, отвечающий за сохранение данных указанных в полях формы.

Для вывода формы на экран отрисовываем блок следующим образом:

return $form->view();

Метод контроллера отвечающий за обработку формы должен завершаться именно этим методом.

В качестве примера использования все логические шаги объединены в метод админ-контроллера отвечающий за формирование формы:

/**
 * Пример метода админ-контроллера модуля/дополнения
 * формирующего форму публикации
 * @return string HTML
 */
public function postForm()
{
    # создаем объект формы
    $form = \tplAdmin::form($this);
    # указываем заголовок формы
    $form->setTitle('Публикации / Управление');

    # добавляем необходимые поля
    $form->tab('main', 'Общие') # объявляем таб формы
        ->text('title', 'Название', '', false)
        ->textarea('content', 'Содержание', '', false)
        ->checkbox('enabled', 'Опубликовать', true)
        ->datepicker('created', 'Дата публикации');

    # добавляем кнопку сохранения и указываем её название
    $form->buttonSubmit('Отправить');

    # объявляем обработчик сохранения данных
    $form->onSave(function($id, $data){
        return $this->model->postSave($id, $data);
    });

    # отрисовываем форму и возвращаем её приложению
    return $form->view();
}

Интеграции формы в список

Формы являются составляющей частью списков, пример интеграции формы в список вы найдете здесь.

Видимость полей и объединения

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

$form->radio('choice', 'Сделайте выбор', 1)
        ->option('1', 'Да')
        ->option('2', 'Нет');

$form->text('block_1', 'Текстовое поле', '', false)
        ->boundaryInit(['title' => 'Блок №1'])
        ->visibleIf('choice', 1);

$form->number('number1', 'Числовое поле')
        ->boundaryIn('block1');

$form->text('block_2', 'Другое текстовое поле')
        ->boundaryInit(['title' => 'Блок №2'])
        ->visibleIf('choice', 2);

Для визуального объединения полей 'block_1' и 'number1' одной рамкой:

объявляем блок в первом поле, подлежащем объединению, при помощи метода boundaryInit(opts), передав в параметре название блока;
добавляем следующие, входящие в блок поля, методом boundaryIn('block1'), параметром является ключ первого поля вошедшего в блок.

Управлять видимостью поля позволяет метод visibleIf(field_key, field_value) в зависимости от значения field_value поля field_key.

Также можно размещать поля рядом друг с другом в одну строку (объединение по горизонтали), задав их ширину.

$form->text('text_key_together', 'Заголовок полей объединенных в строку', '', false)
        ->width(70);

$form->text('text')
        ->together('text_key_together') # справа от поля text_key_together
        ->width(100);

$form->number('number')
        ->together('text_key_together') # справа от поля text_key_together
        ->width(70);

Осуществляем такое размещение при помощи метода together(first_key_together), указав ключ первого поля, к которому добавляем текущее. Шириной полей управляет метод width(count_px).

Админ-панель Формы Введение

Конструктор форм

Простая форма

Интеграции формы в список

Видимость полей и объединения