guide WIP [skip ci]

docs/guide/start-forms.md

@@ -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.

docs/guide/start-hello.md

@@ -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.