Commit a1f89e6f by Qiang Xue

guide WIP [skip ci]

parent d6f6b7b6
......@@ -17,6 +17,7 @@ Through this tutorial, you will learn
* How to build an HTML form in a [view](structure-views.md).
<a name="creating-model"></a>
Creating a Model
----------------
......@@ -60,6 +61,7 @@ failure will turn on the [[yii\base\Model::hasErrors|hasErrors]] property, and t
[[yii\base\Model::getErrors|errors]] you may learn what validation errors the model has.
<a name="creating-action"></a>
Creating an Action
------------------
......@@ -105,16 +107,115 @@ with the user that the data he has entered is accepted. Otherwise, the `entry` v
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
which is a singleton and is globally accessible through this expression. The application instance
is also a [service locator](concept-service-locator.md) providing service components such as `request`,
`response`, `db`, etc. In the above code, the `request` component is used to get the `$_POST` data.
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.
<a name="creating-views"></a>
Creating Views
--------------
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.
<a name="how-it-works"></a>
How It Works
------------
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.
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.
<a name="magic-explained"></a>
### Magic Explained
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.
<a name="summary"></a>
Summary
-------
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.
......@@ -134,6 +134,6 @@ In this section, you have touched the controller part and the view part in the M
You created an action as part of a controller to handle requests. And you also created a view
to compose response content. There is no model involved because the only data used is the simple `message` parameter.
You also have learned the route concept which is the bridge between user requests and controller actions.
You have also learned the route concept which is the bridge between user requests and controller actions.
In the next section, you will learn how to create a model and add a new page with an HTML form.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment