forms basics

forms.md

@@ -0,0 +1,158 @@
+# Формы в Yii2
+
+## Как и зачем
+
+Формы - часто используемые способы ввода данных от пользователя в Веб. В обычном случае программист сам осуществляет верстку, валидацию и обработку данных из формы, однако несложно заметить, что форма по своей структуре часто пересекается с теми или
+иными структурами данных в коде, структурой СУБД и т. п. Поэтому во многих случаях создание форм можно автоматизировать, исходя из этой структуры
+
+## `Model`
+
+Структура-контейнер для данных из формы называется *моделью*. Именно в этой структуре хранится информация о валидации, названии полей, пояснениях и так далее.
+
+```php
+<?php
+namespace app\models;
+
+use yii\base\Model;
+
+class UserModel extends Model
+{
+    public $login;
+    public $password;
+    public $email;
+    public $verifyCode;
+
+
+    public function rules(){
+        return [
+            [['login', 'password', 'email], 'required'], //обязательные поля
+            ['email', 'email'], //email должен быть email-адресом
+            ['verifyCode', 'captcha'] //КАПЧА
+        ];
+    }
+}
+```
+
+### `rules`
+
+Метод `rules` возвращает требования к полям (валидация и тип) в форме массива.
+
+Некоторые из возможных видов валидаторов, применяемых в `rules`:
+- `required`. Обязательное поле
+- `email`. Адрес электронной почты
+- `['login', 'string', 'max' => 50]`. Тип и длина
+- `['countOfHands', 'min' => 0, 'max' => 2]`. Тип, минимальное и максимальное значение.
+- `['someField', 'validateSomeField']` - валидатор в методе класса
+- `['even', function($attribute, $params, $validator){
+        if (($this->$attribute & 2) == 1){
+            $this->addError($attribute, "It's not even");
+        }
+    }]` Валидатор с помощью коллбэк-функции.
+- `when` позволяет сделать условную валидацию, т. е. валидацию, которая работает или нет в зависимости от внешних условий.
+
+Так же есть возможность задавать **JS** код для валидации на клиенте.
+http://www.yiiframework.com/doc-2.0/guide-input-validation.html#inline-validators
+
+
+### Имя правила валидации.
+
+Для удобства вы так же можете задавать правило, используя ассоциативный синтаксис массива:
+
+```php
+    ...
+    'password' => [['password'], 'string', 'max' => 60]
+    ...
+```
+
+## Работа с СУБД.
+
+Для того, что бы модель использовать с возможностью сохранения СУБД, следует использовать `ActiveRecord` в качестве предка вашей модели. `ActiveRecord`, в свою очередь, имеет в предках `Model`, таким образом работает прозрачно в качестве модели.
+
+
+## Контроллер и ЭкшОн
+
+```php
+    public function actionForm()
+    {
+        $model = new SomeModel();
+
+        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
+            $model->save();
+            return $this->render('form-confirm', ['model' => $model]);
+        } else {
+            return $this->render('form', ['model' => $model]);
+        }
+    }
+```
+
+В примере выше в случае удачной валидации происходит сохранение модели, в случае же неудачи или первого захода - отображается форма
+
+## View
+
+В базе **HTML** для формы формируется следующим образом:
+
+```php
+<?php
+use yii\helpers\Html;
+use yii\widgets\ActiveForm;
+?>
+<?php $form = ActiveForm::begin(); ?>
+
+    <?= $form->field($model, 'login') ?>
+
+    <?= $form->field($model, 'password') ?>
+
+    <?= $form->field($model, 'email') ?>
+    
+    <?= $form->field($model, 'password')->passwordInput() ?>
+
+    <div class="form-group">
+        <?= Html::submitButton('Отправить', ['class' => 'btn btn-primary']) ?>
+    </div>
+
+<?php ActiveForm::end(); ?>
+```
+
+Для формирования более сложных полей ввода используются методы объекта, возвращаемые методом `field`:
+```php
+$form->field($model, 'password')->passwordInput() 
+```
+Так же есть другие методы:
+
+- `textInput` для ввода текста, позволяет настроить поле ввода и его **label**
+- `input` для поля ввода, можно задать например **HTML5** тип (`email`, `date`, `number`)
+- `fileInput` для загрузки файла
+- `checkboxList` для списка чекбоксов
+- `dropdownList` для выпадающего списка
+- `radioList` для списка радиокнопок
+- `textArea` для полей ввода
+
+### Общие настройки и полей
+
+Можно задать общие настройки формы:
+```php
+    $form = ActiveForm::begin([
+        'id' => 'register-form',
+        'options' => ['class' => 'big']
+    ]) ?>
+```
+
+Можно задать общие настройки полей формы, включая шаблон поля:
+
+```php
+    <?php $form = ActiveForm::begin([
+        'id' => 'register-form',
+        'options' => ['class' => 'big']
+        'fieldConfig' => [
+             'template' => "{label}\n{beginWrapper}\n{input}\n{hint}\n{error}\n{endWrapper}",
+        ],
+    ]); ?>
+```
+
+Так же можно задавать настройки для каждого поля
+
+```php
+ <?= $form->field($model, 'password', [
+                            'template' => '{label}{input}{hint}{error}'
+                        ]
+```