Working with Forms ================== 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 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 how to: * 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 ---------------- 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 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. 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 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, 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 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`, provided in Yii by [[yii\web\Request::post()]]. If the model is successfully populated (i.e., if the user has submitted the HTML form), the action will call [[yii\base\Model::validate()|validate()]] to make sure the values entered are valid. > 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. If everything is fine, the action will render a view named `entry-confirm` to confirm the successful submission of the data to the user. If no data is submitted or the data contains errors, the `entry` view will be rendered, wherein the HTML form will be shown, along with any validation error messages. > Note: In this very simple example we just render the confirmation page upon valid data submission. In practice, you should consider using [[yii\web\Controller::refresh()|refresh()]] or [[yii\web\Controller::redirect()|redirect()]] to avoid [form resubmission problems](http://en.wikipedia.org/wiki/Post/Redirect/Get). Creating Views -------------- 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 in the file `views/site/entry-confirm.php`. ```php
You have entered the following information: