diff --git a/docs/guide/start-forms.md b/docs/guide/start-forms.md index dd7d90f10a..305ce9c235 100644 --- a/docs/guide/start-forms.md +++ b/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). + 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. + 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. + 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 + +

You have entered the following information:

+ + +``` + +The `entry` view displays an HTML form. It should be stored as the file `views/site/entry.php`. + +```php + + + + field($model, 'name') ?> + + field($model, 'email') ?> + +
+ 'btn btn-primary']) ?> +
+ + +``` + +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. + + + 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. + + + +### 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 +field($model, 'name')->label('Your Name') ?> +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. + + + 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. diff --git a/docs/guide/start-hello.md b/docs/guide/start-hello.md index aee86e4c77..7f0379df3d 100644 --- a/docs/guide/start-hello.md +++ b/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.