guide WIP [skip ci]

docs/guide/structure-models.md

@@ -23,30 +23,15 @@ Please refer to the relevant documentation for more details about these advanced
 
 ## Attributes <a name="attributes"></a>
 
-Attributes are the properties that represent business data. By default, attributes are *non-static public*
-member variables if your model class extends directly from [[yii\base\Model]].
+Models represent business data in terms of *attributes*. Each attribute is like a publicly accessible property
+of a model. The method [[yii\base\Model::attributes()]] specifies what attributes a model class has.
 
-The following code creates a `ContactForm` model class with four attributes: `name`, `email`, `subject` and `body`.
-This model represents the input data that is received from an HTML form.
-
-```php
-namespace app\models;
-
-use yii\base\Model;
-
-class ContactForm extends Model
-{
-    public $name;
-    public $email;
-    public $subject;
-    public $body;
-}
-```
-
-Naturally, you can access an attribute like accessing a normal object property:
+You can access an attribute like accessing a normal object property:
 
 ```php
 $model = new \app\models\ContactForm;
+
+// "name" is an attribute of ContactForm
 $model->name = 'example';
 echo $model->name;
 ```
@@ -68,12 +53,33 @@ foreach ($model as $name => $value) {
 }
 ```
 
-### Extending model attributes
 
-The method [[yii\base\Model::attributes()]] defines and returns the names of the attributes in a model.
-You may override this method to support different ways of defining attributes. For example, [[yii\db\ActiveRecord]]
-does so by returning table column names as attribute names. Note that you may also need to override the magic
-methods such as `__get()`, `__set()` so that the attributes can be accessed like normal object properties.
+### Defining Attributes <a name="defining-attributes"></a>
+
+By default, if your model class extends directly from [[yii\base\Model]], all its *non-static public* member
+variables are attributes. For example, the `ContactForm` model class below has four attributes: `name`, `email`,
+`subject` and `body`. The `ContactForm` model is used to represent the input data received from an HTML form.
+
+```php
+namespace app\models;
+
+use yii\base\Model;
+
+class ContactForm extends Model
+{
+    public $name;
+    public $email;
+    public $subject;
+    public $body;
+}
+```
+
+
+You may override [[yii\base\Model::attributes()]] to define attributes in a different way. The method should
+return the names of the attributes in a model. For example, [[yii\db\ActiveRecord]] does so by returning
+the column names of the associated database table as its attribute names. Note that you may also need to
+override the magic methods such as `__get()`, `__set()` so that the attributes can be accessed like
+normal object properties.
 
 
 ## Attribute Labels <a name="attribute-labels"></a>
@@ -82,6 +88,15 @@ When displaying values or getting input for attributes, you often need to displa
 with attributes. For example, given an attribute named `firstName`, you may want to display a label `First Name`
 which is more user-friendly when displayed to end users in places such as form inputs and error messages.
 
+You can get the label of an attribute by calling [[yii\base\Model::getAttributeLabel()]]. For example,
+
+```php
+$model = new \app\models\ContactForm;
+
+// displays "Label"
+echo $model->getAttributeLabel('name');
+```
+
 By default, attribute labels are automatically generated from attribute names. The generation is done by
 the method [[yii\base\Model::generateAttributeLabel()]]. It will turn camel-case variable names into
 multiple words with the first letter in each word in upper case. For example, `username` becomes `Username`,
@@ -292,13 +307,10 @@ According to the above validation steps, an attribute will be validated if and o
 an active attribute declared in `scenarios()` and it is associated with one or multiple active rules
 declared in `rules()`.
 
-Yii provides a set of built-in validators to support commonly needed data validation tasks. You may also
-create your own validators by extending [[yii\validators\Validator]] or writing an inline validation method
-within model classes. For more details about the built-in validators and how to create your own validators,
-please refer to the [Input Validation](input-validation.md) section.
-
-> Note: As a rule of thumb, never trust the data coming from end users and always validate them before
-  putting them to some good use.
+Yii provides a set of [built-in validators](tutorial-core-validators.md) to support commonly needed data
+validation tasks. You may also create your own validators by extending [[yii\validators\Validator]] or
+writing an inline validation method within model classes. For more details about the built-in validators
+and how to create your own validators, please refer to the [Input Validation](input-validation.md) section.
 
 
 ## Massive Assignment <a name="massive-assignment"></a>