FFCMS Wiki

Официальная документация разработчика и администратора

Инструменты пользователя

Инструменты сайта


helper:html:form

HTML-помощник: Формы (Forms)

Помощник формы(forms) предназначен для быстрой генерации готового html-каркаса форм и передачи входящих данных в значения атрибутов модели. Помощник формы работает на основе моделей для отображения и обработки пользовательского ввода данных.

Введение в использование

Для автоматической генерации кода формы и обработки пользовательского ввода данных в первую очередь необходимо сгенерировать модель с рядом атрибутов. Наша модель будет выглядеть следующим образом:

model

class Data extends Model
{
    public $login;
    public $password;
}

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

controller action

public function actionTest()
{
    $model = new Data();
 
    return App::$View->render('test_view', [
        'model' => $model
    ]);
}

А конечное представление будет выглядеть следующим образом:

view

<h1>Test form</h1>
<hr />
<?php $form = new Form($model, ['class' => 'form-horizontal', 'method' => 'post']); ?>
<?= $form->start(); ?>
 
<?= $form->field('login', 'text', ['class' => 'form-control']) ?>
<?= $form->field('password', 'password', ['class' => 'form-control']) ?>
 
<?= $form->submitButton('Save', ['class' => 'btn btn-success']); ?>
 
<?= $form->finish() ?>

После рендеринга данный view примет следующую html структуру (код символичен, шаблоны не учтены):

<form name="DataForm" class="form-horizontal" method="post">
 
<label for="DataForm-login">Login</label>
<input type="text" name="DataForm[login]" class="form-control" id="DataFormLogin" />
 
<label for="DataForm-password">Password</label>
<input type="password" name="DataForm[password]" class="form-control" id="DataFormPassword" />
 
<input type="submit" name="DataForm[submit]" value="Save" class="btn btn-success" />
 
</form>

и будет иметь следующий вид:

 form example

Кроме того сгенерированный html код будет содержать и код javascript-валидации полей, правила для которых были указаны в модели в методе rules().

Инициация формы

Как мы уже отмечали ранее, в введении, для инициации элемента форма необходима предварительная инициация одной (или нескольких) модели, которая будет заниматься обработкой введенных пользовательских данных в поля формы.

Инициация объекта формы происходит классическим образом инициации класса Form:

use Ffcms\Core\Helper\HTML\Form;
 
$form = new Form($model, $properties, $layers);

В качестве параметров инициации передаются следующие:

  1. $model - должна быть обязательно передана как экземпляр класса, унаследованного от Ffcms\Core\Arch\Model (иными словами - должен быть передан экземпляр инициированной модели)
  2. $properties - необязательный параметр свойств для тега <form>, может быть передан в виде массива ключ-значение, где ключ это свойство атрибута тега
  3. $layers - необязательный параметр нестандартных шаблонов для генерации форм. Может быть передан в виде массива ключ-значение, где ключ - параметр базового шаблона (base, checkbox, checkboxes, radio, jsnotify - все они хранятся в директории шаблона, см. /native/form/), а значение - путь, относительно директории текущего шаблона до файла с новым шаблоном подложки

После инициации объекта модели необходимо отобразить корневой <form> тег, а по завершении генерации полей формы - закрыть корневой тег </form>:

echo $form->start();
 
// ... some form code ...
 
echo $form->finish();

Так же следует помнить, что можно отключить автоматическую генерацию правил валидации формы при вызове метода $form→finish(false) выставив false в качестве атрибута вызова метода.

Поля формы (fields)

Поля являются основными структурными единицами формы: они предназначены для обмена данными с пользователем. По своей натуре, поля (fields) форм это лишь уровень надстройки над классическим input, textarea, позволяющий существенно упростить механизм принятия, обработки и сохранения входящих пользовательских данных.

Итак, рассмотрим классический пример генерации текстового поля, на основе модели Data, рассмотренной выше:

// on top of $form = new Form((new Data())) or something like that ;D
echo $form->field('login', 'text', ['class' => 'form-horizontal'], __('Please, enter your login data'));

В результате будет сгенерировано поле вида <input id=«ModelName-login» type=«text» name=ModelName[login] … /> вместе с лейблом: <label for=«ModelName-login»>Login:</label> и с текстом-помощником <p class=«helper»>Please, enter your login data</p> (стоит отметить, обертка __() это сокращенный вызов метода интернационализации приложений). По большей степени такая автоматическая генерация полей формы позволяет практически напрочь забыть о проблемах именования полей и всех вспомогательных элементов поля и контролем за его отправкой.

Уже в дальнейшем, в теле действия контроллера входящие данные из этого поля могут быть получены, проверены и обработаны - см. руководство по моделям.

Итак, разберемся с возможными параметрами отображения полей. Общий синтаксис таков: $form→field($fieldName, $fieldType, $properties, $helperText), где:

  1. $fieldName - название поля, должно быть так же объявлено в переданной в форму модели в виде публичного атрибута, иначе повлечет вызов ошибки SyntaxException
  2. $fieldType - тип отображаемого поля, см. следующий раздел
  3. $properties - свойства тега поля, может быть передано в виде массива ключ-значение, где ключ - название свойства тега
  4. $helperText - вспомогательный текст для поля

Типы полей

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

Тип поля Описание Пример Form Синоним в HTML
text Генерация поля для небольшого объема публичных текстовых входящих данных $form→field('obj', 'text') <input type=«text» />
password Генерация защищенного поля для заполнения пароля $form→field('obj', 'password') <input type=«password» />
email Генерация поля для ввода/отображения email по стандарту html5 $form→field('obj', 'email') <input type=«email» />
checkbox Генерация поля вида «флажок» для обозначения on/off состояния $form→field('obj', 'checkbox') <input type=«checkbox» />
checkboxes Генерация нескольких полей вида «флажок» для обозначения on/off состояния $form→field('obj', 'checkboxes', ['options' ⇒ ['one', 'two']]) <input type=«checkbox» name=«one» /> <input type=«checkbox» name=«two» />
select Генерация поля вида «список» с несколькими значениями. Возможен выбор ТОЛЬКО одного значения $form→field('obj', 'select', ['options' ⇒ ['one', 'two']) <select> <option value=«one»>one</option> <option value=«two»>two</option> </select>
multiselect Генерация поля вида «список» с несколькими значениями. Возможен выбор НЕСКОЛЬКИХ значений $form→field('obj', 'multiselect', ['options' ⇒ ['one', 'two']) <select multiple> <option value=«one»>one</option> <option value=«two»>two</option> </select>
textarea Генерация поля вида «произвольный текст» для ввода/отображения большого объема публичных текстовых данных $form→field('obj', 'textarea') <textarea>…</textarea>
file Генерация поля для загрузки файла. Следует так же указать в свойства формы - enctype=«multipart/form-data», а в модели определить метод sources() и указать для соответствующего атрибута ['obj' ⇒ 'file'] $form→field('obj', 'file') <input type=«file» />
hidden Генерация скрытого поля $form→field('obj', 'hidden', ['value' ⇒ 'fieldValue']) <input type=«hidden» value=«fieldValue» />
radio Генерация поля вида «переключатель» с несколькими различными состояниями $form→field('obj', 'radio', ['options' ⇒ 'one', 'two', 'three']) <input type=«radio» name=«obj» value=«one» /> <input type=«radio» name=«obj» value=«two» /> <input type=«radio» name=«obj» value=«three» />
div Генерация текстового блока для отображения содержимого $form→field('obj', 'div', ['value' ⇒ 'some text'])

some text

captcha Генерация специфичного поля с изображением и полем для ввода - классическая реализация капчи $form→field('obj', 'captcha') -
helper/html/form.txt · Последние изменения: 2017/09/01 13:04 (внешнее изменение)