From 5e56bc5ff05f54403df879db8045f7c6df4b3bef Mon Sep 17 00:00:00 2001 From: Larry Ullman Date: Mon, 16 Jun 2014 13:57:31 -0400 Subject: [PATCH] Edited --- docs/guide/start-forms.md | 112 +++++++++++++++++++++----------------- 1 file changed, 62 insertions(+), 50 deletions(-) diff --git a/docs/guide/start-forms.md b/docs/guide/start-forms.md index 34de19c7d5..6c2c4f90eb 100644 --- a/docs/guide/start-forms.md +++ b/docs/guide/start-forms.md @@ -1,25 +1,25 @@ Working with Forms ================== -In this section, we will describe how to create a new page to get data from users. +This section describes how to create a new page with a form for getting data from users. The page will display a form with a name input field and an email input field. -After getting these data from a user, the page will echo them back to the user for confirmation. +After getting those two pieces of information from the user, the page will echo the entered values back for confirmation. 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 +Through this tutorial, you will learn how to: -* How to create a [model](structure-models.md) to represent the data entered by a user; -* How to declare rules to validate the data entered by users; -* How to build an HTML form in a [view](structure-views.md). +* Create a [model](structure-models.md) to represent the data entered by a user through a form +* Declare rules to validate the data entered +* Build an HTML form in a [view](structure-views.md) Creating a Model ---------------- -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) +The data to be requested from the user will be represented by an `EntryForm` model class as shown below and +saved 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 @@ -44,26 +44,38 @@ class EntryForm extends Model } ``` -The class extends from [[yii\base\Model]], a base class provided by Yii that is commonly used to +The class extends from [[yii\base\Model]], a base class provided by Yii, 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 +> Info: [[yii\base\Model]] is used as a parent for model classes *not* associated with database tables. [[yii\db\ActiveRecord]] is normally the parent for model classes that do correspond to database tables. -* both the `name` and `email` data are required; -* the `email` data must be a valid email address. +The `EntryForm` class contains two public members, `name` and `email`, which are used to store +the data entered by the user. It also contains a method named `rules()`, which returns a set +of rules for validating the data. The validation rules declared above state that + +* both the `name` and `email` values are required +* the `email` data must be a syntactically 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. +its [[yii\base\Model::validate()|validate()]] to trigger the data validation routines. A data validation +failure will set the [[yii\base\Model::hasErrors|hasErrors]] property to true, and you may learn what validation errors occurred through [[yii\base\Model::getErrors|errors]]. + +```php +name = 'Qiang'; +$model->email = 'bad'; +if ($model->validate()) { // Good! +} else { // Failure! + // Use $model->getErrors() +} +``` Creating an Action ------------------ -Next, create an `entry` action in the `site` controller, like you did in the previous section. +Next, you'll need to create an `entry` action in the `site` controller that will use the new model. The process of creating and using actions was explained in the [Saying Hello](start-hello.md) section. ```php Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance - 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. +> Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance, + which is a globally accessible singleton. It is also a [service locator](concept-service-locator.md) that + provides components such as `request`, `response`, `db`, etc. to support specific functionality. + In the above code, the `request` component of the application instance 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. +Finally, create two view files named `entry-confirm` and `entry`. These will be rendered by the `entry` action, +as just described. -The `entry-confirm` view simply displays the name and email data. It should be stored as the file `views/site/entry-confirm.php`. +The `entry-confirm` view simply displays the name and email data. It should be stored in the file `views/site/entry-confirm.php`. ```php ``` -The `entry` view displays an HTML form. It should be stored as the file `views/site/entry.php`. +The `entry` view displays an HTML form. It should be stored in the file `views/site/entry.php`. ```php Warning: Client-side validation is a conveniences that provides for a better user experience. Server-side validation is always required, whether or not client-side validation is in place. + +The labels for input fields are generated by the `field()` method, using the property names from the model. +For example, the label `Name` will be generated for the `name` property. + +You may customize a label within a view using the following code: ```php @@ -205,18 +217,18 @@ the following code: ``` > 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 + As you will learn later, writing a new widget is also extremely easy. You may want to 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. +In this section of the guide, 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 said data. -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 +You have also learned how to get data from users and how to display data back in the browser. This is a task that +could take you a lot of time when developing an application, but 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. +In the next section, you will learn how to work with databases, which are needed in nearly every application.