start-forms.md 8.16 KB
Newer Older
1 2 3
Working with Forms
==================

Qiang Xue committed
4 5
In this section, we will describe how to create a new page to get data from users.
The page will display a form with a name input field and an email input field.
Qiang Xue committed
6
After getting these data from a user, the page will echo them back to the user for confirmation.
Qiang Xue committed
7 8 9 10 11 12

To achieve this goal, besides creating an [action](structure-controllers.md) and
two [views](structure-views.md), you will also create a [model](structure-models.md).

Through this tutorial, you will learn

Qiang Xue committed
13
* How to create a [model](structure-models.md) to represent the data entered by a user;
Qiang Xue committed
14 15 16 17
* How to declare rules to validate the data entered by users;
* How to build an HTML form in a [view](structure-views.md).


Qiang Xue committed
18
Creating a Model <a name="creating-model"></a>
Qiang Xue committed
19 20
----------------

Qiang Xue committed
21 22 23 24 25
To represent the data entered by a user, create an `EntryForm` model class as shown below and
save the class in the file `models/EntryForm.php`. Please refer to the [Class Autoloading](concept-autoloading.md)
section for more details about the class file naming convention.

```php
26 27
<?php

Qiang Xue committed
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
namespace app\models;

use yii\base\Model;

class EntryForm extends Model
{
    public $name;
    public $email;

    public function rules()
    {
        return [
            [['name', 'email'], 'required'],
            ['email', 'email'],
        ];
    }
}
```

The class extends from [[yii\base\Model]], a base class provided by Yii that is commonly used to
represent form data.

The class contains two public members, `name` and `email`, which are used to keep
the data entered by the user. It also contains a method named `rules()` which returns a set
of rules used for validating the data. The validation rules declared above state that

* both the `name` and `email` data are required;
* the `email` data must be a valid email address.

If you have an `EntryForm` object populated with the data entered by a user, you may call
its [[yii\base\Model::validate()|validate()]] to trigger the data validation. A data validation
failure will turn on the [[yii\base\Model::hasErrors|hasErrors]] property, and through
[[yii\base\Model::getErrors|errors]] you may learn what validation errors the model has.


Qiang Xue committed
63
Creating an Action <a name="creating-action"></a>
Qiang Xue committed
64 65
------------------

Qiang Xue committed
66 67 68
Next, create an `entry` action in the `site` controller, like you did in the previous section.

```php
69 70
<?php

Qiang Xue committed
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
namespace app\controllers;

use Yii;
use yii\web\Controller;
use app\models\EntryForm;

class SiteController extends Controller
{
    // ...existing code...

    public function actionEntry()
    {
        $model = new EntryForm;

        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
            // valid data received in $model

            // do something meaningful here about $model ...

            return $this->render('entry-confirm', ['model' => $model]);
        } else {
            // either the page is initially displayed or there is some validation error
            return $this->render('entry', ['model' => $model]);
        }
    }
}
```

The action first creates an `EntryForm` object. It then tries to populate the model
with the data from `$_POST` which is provided in Yii through [[yii\web\Request::post()]].
If the model is successfully populated (i.e., the user has submitted the HTML form),
it will call [[yii\base\Model::validate()|validate()]] to make sure the data entered
are valid.

If everything is fine, the action will render a view named `entry-confirm` to confirm
with the user that the data he has entered is accepted. Otherwise, the `entry` view will
be rendered, which will show the HTML form together with the validation error messages (if any).

> Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance
Qiang Xue committed
110 111 112
  which is a globally accessible singleton. It is also a [service locator](concept-service-locator.md)
  providing components, such as `request`, `response`, `db`, etc. to support specific functionalities.
  In the above code, the `request` component is used to access the `$_POST` data.
Qiang Xue committed
113 114


Qiang Xue committed
115
Creating Views <a name="creating-views"></a>
Qiang Xue committed
116 117
--------------

Qiang Xue committed
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
Finally, create two views named `entry-confirm` and `entry` that are rendered by the `entry` action,
as described in the last subsection.

The `entry-confirm` view simply displays the name and email data. It should be stored as the file `views/site/entry-confirm.php`.

```php
<?php
use yii\helpers\Html;
?>
<p>You have entered the following information:</p>

<ul>
    <li><label>Name</label>: <?= Html::encode($model->name) ?></li>
    <li><label>Email</label>: <?= Html::encode($model->email) ?></li>
</ul>
```

The `entry` view displays an HTML form. It should be stored as the file `views/site/entry.php`.

```php
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
?>
<?php $form = ActiveForm::begin(); ?>

    <?= $form->field($model, 'name') ?>

    <?= $form->field($model, 'email') ?>

    <div class="form-group">
        <?= Html::submitButton('Submit', ['class' => 'btn btn-primary']) ?>
    </div>

<?php ActiveForm::end(); ?>
```

The view uses a powerful [widget](structure-widgets.md) called [[yii\widgets\ActiveForm|ActiveForm]] to
build the HTML form. The `begin()` and `end()` methods of the widget render the opening and close
form tags, respectively. Between the two method calls, input fields are created by the
[[yii\widgets\ActiveForm::field()|field()]] method. The first input field is about the "name" data,
and the second the "email" data. After the input fields, the [[yii\helpers\Html::submitButton()]] method
is called to generate a submit button.


Qiang Xue committed
163
How It Works <a name="how-it-works"></a>
Qiang Xue committed
164 165
------------

Qiang Xue committed
166 167 168 169 170 171 172 173 174 175 176
To see how it works, use your browser to access the following URL:

```
http://hostname/index.php?r=site/entry
```

You will see a page displaying a form with two input fields. In front of each input field, a label
is also displayed indicating what data you need to enter. If you click the submit button without
entering anything, or if you do not provide a valid email address, you will see an error message that
is displayed next to each problematic input field.

177 178
![Form with Validation Errors](images/start-form-validation.png)

Qiang Xue committed
179 180 181
After entering a valid name and email address and clicking the submit button, you will see a new page
displaying the data that you just entered.

182 183 184
![Confirmation of Data Entry](images/start-entry-confirmation.png)


Qiang Xue committed
185

Qiang Xue committed
186
### Magic Explained <a name="magic-explained"></a>
Qiang Xue committed
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211

You may wonder how the HTML form works behind the scene, because it seems almost magical that it can
display a label for each input field and show error messages if you do not enter the data correctly
without reloading the page.

Yes, the data validation is actually done on the client side using JavaScript as well as on the server side.
[[yii\widgets\ActiveForm]] is smart enough to extract the validation rules that you have declared in `EntryForm`,
turn them into JavaScript code, and use the JavaScript to perform data validation. In case you have disabled
JavaScript on your browser, the validation will still be performed on the server side, as shown in
the `actionEntry()` method. This ensures data validity in all circumstances.

The labels for input fields are generated by the `field()` method based on the model property names.
For example, the label `Name` will be generated for the `name` property. You may customize a label by
the following code:

```php
<?= $form->field($model, 'name')->label('Your Name') ?>
<?= $form->field($model, 'email')->label('Your Email') ?>
```

> Info: Yii provides many such widgets to help you quickly build complex and dynamic views.
  As you will learn later, writing a new widget is also extremely easy. You may turn much of your
  view code into reusable widgets to simplify view development in future.


Qiang Xue committed
212
Summary <a name="summary"></a>
Qiang Xue committed
213
-------
Qiang Xue committed
214 215 216 217 218 219 220 221 222

In this section, you have touched every part in the MVC design pattern. You have learned how
to create a model class to represent the user data and validate them.

You have also learned how to get data from users and how to display them back. This is a task that
could take you a lot of time when developing an application. Yii provides powerful widgets
to make this task very easy.

In the next section, you will learn how to work with databases which are needed in nearly every application.