Merge branch 'master' of https://github.com/yii2-chinesization/yii2

b0a40542 · riverlet · ea8be6e7 · 83c0dd21 · b0a40542 · b0a40542
Commit b0a40542 authored Jun 27, 2014 by riverlet
8 changed files
--- a/docs/guide-zh-CN/README.md
+++ b/docs/guide-zh-CN/README.md
@@ -23,7 +23,7 @@ Yii 2.0 权威指南
 * **已定稿** [使用 Forms](start-forms.md)
 * **已定稿** [玩转 Databases](start-databases.md)
 * **已定稿** [用 Gii 生成代码](start-gii.md)
-* **已定稿** [更上一层楼](start-looking-head.md)
+* **已定稿** [更上一层楼](start-looking-ahead.md)
 应用结构
 --------

--- a/docs/guide-zh-CN/concept-properties.md
+++ b/docs/guide-zh-CN/concept-properties.md
+属性（Property）
+==========
+In PHP, class member variables are also called *properties*. These variables are part of the class definition, and are used
+to represent the state of a class instance (i.e., to differentiate one instance of the class from another). In practice, you may often want to handle the reading or writing of properties in special ways. For example, you may want to trim a string when it is being assigned
+to a `label` property. You could use the following code to achieve this task:
+```php
+$object->label = trim($label);
+```
+The drawback of the above code is that you have to call `trim()` everywhere in your code where you met set the `label`
+property. If in the future, the `label` property gets a new requirement, such as the first letter must be captialized, you would again have to modify every bit of code that assigns a value to `label`. The repetition of code leads to bugs and is a practice you want to avoid as much as possible.
+To solve this problem, Yii introduces a base class called [[yii\base\Object]] that supports defining properties
+based on *getter* and *setter* class methods. If a class needs such support, it should extend from
+[[yii\base\Object]] or a child class.
+> Info: Nearly every core class in the Yii framework extends from [[yii\base\Object]] or a child class.
+  This means that whenever you see a getter or setter in a core class, you can use it like a property.
+A getter method is a method whose name starts with the word `get`; a setter method starts with `set`.
+The name after the `get` or `set` prefix defines the name of a property. For example, a getter `getLabel()` and/or
+a setter `setLabel()` defines a property named `label`, as shown in the following code:
+```php
+namespace app\components;
+use yii\base\Object;
+class Foo extend Object
+{
+    private $_label;
+    public function getLabel()
+    {
+        return $this->_label;
+    }
+    public function setLabel($value)
+    {
+        $this->_label = trim($value);
+    }
+}
+```
+(To be clear, the getter and setter methods create the property `label`, which in this case internally refer to a private attributed named `_label`.)
+Properties defined by getters and setters can be used like class member variables. The main difference is that
+when such a property is being read, the corresponding getter method will be called;  when the property is
+being assigned a value, the corresponding setter method will be called. For example:
+```php
+// equivalent to $label = $object->getLabel();
+$label = $object->label;
+// equivalent to $object->setLabel('abc');
+$object->label = 'abc';
+```
+A property defined by a getter without a setter is *read only*. Trying to assign a value to such a property will cause
+an [[yii\base\InvalidCallException|InvalidCallException]]. Similarly, a property defined by a setter without a getter
+is *write only*, and trying to read such a property will also cause an exception. It is not common to have write-only
+properties.
+There are several special rules for, and limitations on, the properties defined via getters and setters:
+* The names of such properties are *case-insensitive*. For example, `$object->label` and `$object->Label` are the same.
+  This is because method names in PHP are case-insensitive.
+* If the name of such a property is the same as a class member variable, the latter will take precedence.
+  For example, if the above `Foo` class has a member variable `label`, then the assignment `$object->label = 'abc'`
+  will affect the member variable 'label', that line would not call the  `setLabel()` setter method.
+* These properties do not support visibility. It makes no difference for the visibility of a property
+  if the defining getter or setter method is public, protected or private.
+* The properties can only be defined by *non-static* getters and/or setters. Static methods will not be treated in this same manner.
+Returning back to the problem  described at the beginning of this guide, instead of calling `trim()` everywhere a `label` value is assigned, `trim()` only needs to be invoked within the setter `setLabel()`. And if a new requirement comes that requires the label be initially capitalized, the `setLabel()` method can quickly be modified without touching any other code. The one change will universally affect every assignment to `label`.
--- a/docs/guide-zh-CN/concept-service-locator.md
+++ b/docs/guide-zh-CN/concept-service-locator.md
+服务定位器（Service Locator）
+===============
+服务定位器是一个了解如何提供各种应用所需的服务（或组件）的对象。在一个服务定位器中，每一个组件都只有一个单独的实例，并通过
+ID 唯一地标识。用这个 ID 就能从服务定位器中得到这个组件。
+在 Yii 中，服务定位器只是 [[yii\di\ServiceLocator]] 或其子类的一个实例。
+最最常用的服务定位器一般是 *application（应用）* 对象，可以通过 `\Yii::$app` 访问。它所提供的服务被称为
+*application components（应用组件）*，比如：`request`、`response`、`urlManager`（分别是请求、响应、Url 管理器）组件。你可以通过服务定位器所提供的功能，非常容易地配置这些组件，或甚至是用你自己的实现替换掉他们。
+除了 Application 对象，每一个模块对象本身也是一个服务定位器。
+要使用一个服务定位器，第一步是要注册相关组件。组件可以通过 [[yii\di\ServiceLocator::set()]]
+方法进行注册。以下的方法展示了注册组件的不同方法：
+```php
+use yii\di\ServiceLocator;
+use yii\caching\FileCache;
+$locator = new ServiceLocator;
+// 通过一个可用于创建该组件的类名，注册 "cache" （缓存）组件。
+$locator->set('cache', 'yii\caching\ApcCache');
+// 通过一个可用于创建该组件的配置数组，注册 "db" （数据库）组件。
+$locator->set('db', [
+    'class' => 'yii\db\Connection',
+    'dsn' => 'mysql:host=localhost;dbname=demo',
+    'username' => 'root',
+    'password' => '',
+]);
+// 通过一个能返回该组件的匿名函数，注册 "search" 组件。
+$locator->set('search', function () {
+    return new app\components\SolrService;
+});
+// 用组件注册 "pageCache" 组件
+$locator->set('pageCache', new FileCache);
+```
+一旦组件被注册成功，你可以任选以下两种方式之一，通过它的 ID 访问它：
+```php
+$cache = $locator->get('cache');
+// 或者
+$cache = $locator->cache;
+```
+如上文所示， [[yii\di\ServiceLocator]] 允许你通过组件 ID 像访问一个属性值那样访问一个组件。当你第一次访问某组件时，
+[[yii\di\ServiceLocator]] 会通过该组件的注册信息创建一个该组件的实例，并返回它。之后，如果再次访问，则服务定位器会返回同一个实例。
+你可以通过 [[yii\di\ServiceLocator::has()]] 检查某组件 ID 是否被注册。
+若你用一个无效的 ID 调用 [[yii\di\ServiceLocator::get()]]，则会抛出一个异常。
+因为服务定位器，经常会在创建时附带[配置信息](concept-configurations.md)，因此我们提供了一个可写的属性，名为
+[[yii\di\ServiceLocator::setComponents()|components]]，这样就可以配置该属性，或一次性注册多个组件。下面的代码展示了如何用一个配置数组，配置一个应用并注册
+"db"，"cache" 和 "search" 三个组件：
+```php
+return [
+    // ...
+    'components' => [
+        'db' => [
+            'class' => 'yii\db\Connection',
+            'dsn' => 'mysql:host=localhost;dbname=demo',
+            'username' => 'root',
+            'password' => '',
+        ],
+        'cache' => 'yii\caching\ApcCache',
+        'search' => function () {
+            return new app\components\SolrService;
+        },
+    ],
+];
+```
--- a/docs/guide-zh-CN/start-databases.md
+++ b/docs/guide-zh-CN/start-databases.md
+使用数据库
+======================
+本小节将介绍如何如何创建一个从数据表 `country` 中获取国家数据并显示出来的页面。为了实现这个目标，你将会配置一个数据库连接，创建一个[活动记录](db-active-record.md)类，并且创建一个[操作](structure-controllers.md)及一个[视图](structure-views.md)。
+贯穿整个小节，你将会学到：
+* 配置一个数据库连接
+* 定义一个活动记录类
+* 使用活动记录从数据库中查询数据
+* 以分页方式在视图中显示数据
+请注意，为了掌握本小节你应该具备最基本的数据库知识和使用经验。尤其是你应该知道如何创建数据库，如何通过数据库终端执行 SQL 语句。
+准备数据库 <a name="preparing-database"></a>
+--------------------
+首先创建一个名为 `yii2basic` 的数据库，你的应用将从这个数据库中获取数据。你可以创建 SQLite，MySQL，PostregSQL，MSSQL 或 Oracle 数据库，Yii 内置多种数据库支持。简单起见后面的内容将以 MySQL 为例做演示。
+然后在数据库中创建一个名为 `country` 的表并插入简单的数据。可以执行下面的语句：
+```sql
+CREATE TABLE `country` (
+  `code` CHAR(2) NOT NULL PRIMARY KEY,
+  `name` CHAR(52) NOT NULL,
+  `population` INT(11) NOT NULL DEFAULT '0'
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+INSERT INTO `Country` VALUES ('AU','Australia',18886000);
+INSERT INTO `Country` VALUES ('BR','Brazil',170115000);
+INSERT INTO `Country` VALUES ('CA','Canada',1147000);
+INSERT INTO `Country` VALUES ('CN','China',1277558000);
+INSERT INTO `Country` VALUES ('DE','Germany',82164700);
+INSERT INTO `Country` VALUES ('FR','France',59225700);
+INSERT INTO `Country` VALUES ('GB','United Kingdom',59623400);
+INSERT INTO `Country` VALUES ('IN','India',1013662000);
+INSERT INTO `Country` VALUES ('RU','Russia',146934000);
+INSERT INTO `Country` VALUES ('US','United States',278357000);
+```
+于是便有了一个名为 `yii2basic` 的数据库，在这个数据库中有一个包含三个字段的数据表 `country`，表中有十行数据。
+配置数据库连接 <a name="configuring-db-connection"></a>
+---------------------------
+开始之前，请确保你已经安装了 PHP [PDO](http://www.php.net/manual/en/book.pdo.php) 扩展和你所使用的数据库的 PDO 驱动（例如 MySQL 的 `pdo_mysql`）。对于使用关系型数据库来讲，这是基本要求。
+驱动和扩展安装可用后，打开 `config/db.php` 修改里面的配置参数对应你的数据库配置。该文件默认包含这些内容：
+```php
+<?php
+return [
+    'class' => 'yii\db\Connection',
+    'dsn' => 'mysql:host=localhost;dbname=yii2basic',
+    'username' => 'root',
+    'password' => '',
+    'charset' => 'utf8',
+];
+```
+`config/db/php` 是一个典型的基于文件的[配置](concept-configurations.md)工具。这个文件配置了数据库连接 [[yii\db\Connection]] 的创建和初始化参数，应用的 SQL 查询正是基于这个数据库。
+上面配置的数据库连接可以在应用中通过 `Yii::$app->db` 访问。
+> 补充：`config/db.php` 将被包含在应用配置文件 `config/web.php` 中，后者指定了整个[应用](structure-applications.md)如何初始化。请参考[配置](concept-configurations.md)小节了解更多信息。
+创建活动记录 <a name="creating-active-record"></a>
+-------------------------
+创建一个继承自[活动记录](db-active-record.md)类的类 `Country`，把它放在 `models/Country.php`，去表示和获取 `country` 表的数据。
+```php
+<?php
+namespace app\models;
+use yii\db\ActiveRecord;
+class Country extends ActiveRecord
+{
+}
+```
+这个 `Country` 类继承自 [[yii\db\ActiveRecord]]。你不用在里面写任何代码。只需要像现在这样，Yii 就能根据类名去猜测对应的数据表名。
+> 补充：如果类名和数据表名不能直接对应，你可以重写 [[yii\db\ActiveRecord::tableName()|tableName()]] 方法去显式指定相关表名。
+使用 `Country` 类你可以很容易地操作 `country` 表数据，就像这段代码：
+```php
+use app\models\Country;
+// 获取 country 表的所有行并以 name 排序
+$countries = Country::find()->orderBy('name')->all();
+// 获取主键为 “US” 的行
+$country = Country::findOne('US');
+// 输出 “United States”
+echo $country->name;
+// 修改 name 为 “U.S.A.” 并在数据库中保存更改
+$country->name = 'U.S.A.';
+$country->save();
+```
+> 补充：活动记录是面向对象、功能强大的访问和操作数据库数据的方式。你可以在[活动记录](db-active-record.md)小节了解更多信息。除此之外你还可以使用另一种更原生的称做[数据访问对象](db-dao)的方法操作数据库数据。
+创建操作 <a name="creating-action"></a>
+------------------
+为了向最终用户显示国家数据，你需要创建一个操作。相比之前小节掌握的在 `site` 控制器中创建操作，在这里为所有和国家有关的数据新建一个控制器更加合理。新控制器名为 `CountryController`，并在其中创建一个 `index` 操作，如下：
+```php
+<?php
+namespace app\controllers;
+use yii\web\Controller;
+use yii\data\Pagination;
+use app\models\Country;
+class CountryController extends Controller
+{
+    public function actionIndex()
+    {
+        $query = Country::find();
+        $pagination = new Pagination([
+            'defaultPageSize' => 5,
+            'totalCount' => $query->count(),
+        ]);
+        $countries = $query->orderBy('name')
+            ->offset($pagination->offset)
+            ->limit($pagination->limit)
+            ->all();
+        return $this->render('index', [
+            'countries' => $countries,
+            'pagination' => $pagination,
+        ]);
+    }
+}
+```
+把上面的代码保存在 `controllers/CountryController.php`。
+`index` 操作调用了活动记录 `Country::find()` 方法，去生成查询语句并从 `country` 表中取回所有数据。为了限定每个请求所返回的国家数量，查询在 [[yii\data\Pagination]] 对象的帮助下进行分页。 `Pagination` 对象的使命主要有两点：
+* 为 SQL 查询语句设置 `offset` 和 `limit` 从句，确保每个请求只需返回一页数据（本例中每页是 5 行）。
+* 在视图中显示一个由页码列表组成的分页器，这点将在后面的段落中解释。
+在代码末尾，`index` 操作渲染一个名为 `index` 的视图，并传递国家数据和分页信息进去。
+创建视图 <a name="creating-view"></a>
+---------------
+在 `views` 目录下先创建一个名为 `country` 的子目录。这个目录存储所有由 `country` 控制器渲染的视图。在 `views/country` 目录下创建一个名为 `index.php` 的视图文件，内容如下：
+```php
+<?php
+use yii\helpers\Html;
+use yii\widgets\LinkPager;
+?>
+<h1>Countries</h1>
+<ul>
+<?php foreach ($countries as $country): ?>
+    <li>
+        <?= Html::encode("{$country->name} ({$country->code})") ?>:
+        <?= $country->population ?>
+    </li>
+<?php endforeach; ?>
+</ul>
+<?= LinkPager::widget(['pagination' => $pagination]) ?>
+```
+这个视图包含两部分用以显示国家数据。第一部分遍历国家数据并以无序 HTML 列表渲染出来。第二部分使用 [[yii\widgets\LinkPager]] 去渲染从操作中传来的分页信息。小部件 `LinkPager` 显示一个分页按钮的列表。点击任何一个按钮都会跳转到对应的分页。
+尝试下 <a name="trying-it-out"></a>
+-------------
+浏览器访问下面的 URL 看看能否工作：
+```
+http://hostname/index.php?r=country/index
+```
+![国家列表](images/start-country-list.png)
+首先你会看到显示着五个国家的列表页面。在国家下面，你还会看到一个包含四个按钮的分页器。如果你点击按钮 “2”，将会跳转到显示另外五个国家的页面，也就是第二页记录。如果观察仔细点你还会看到浏览器的 URL 变成了：
+```
+http://hostname/index.php?r=country/index&page=2
+```
+在这个场景里，[[yii\data\Pagination|Pagination]] 提供了为数据结果集分页的所有功能：
+* 首先 [[yii\data\Pagination|Pagination]] 把 SELECT 的子查询 `LIMIT 5 OFFSET 0` 数据表示成第一页。因此开头的五条数据会被取出并显示。
+* 然后小部件 [[yii\widgets\LinkPager|LinkPager]] 使用 [[yii\data\Pagination::createUrl()|Pagination::createUrl()]] 方法生成的 URL 去渲染翻页按钮。URL 中包含必要的参数 `page` 才能查询不同的页面编号。
+* 如果你点击按钮 “2”，将会发起一个路由为 `country/index` 的新请求。[[yii\data\Pagination|Pagination]] 接收到 URL 中的 `page` 参数把当前的页码设为 2。新的数据库请求将会以 `LIMIT 5 OFFSET 5` 查询并显示。
+总结 <a name="summary"></a>
+-------
+本小节中你学到了如何使用数据库。你还学到了如何取出并使用 [[yii\data\Pagination]] 和 [[yii\widgets\LinkPager]] 显示数据。
+下一小节中你会学到如何使用 Yii 中强大的代码生成器 [Gii](tool-gii.md)，去帮助你实现一些常用的功能需求，例如增查改善（CRUD）数据表中的数据。事实上你之前所写的代码全部都可以由 Gii 自动生成：）
\ No newline at end of file
--- a/docs/guide-zh-CN/start-forms.md
+++ b/docs/guide-zh-CN/start-forms.md
+使用表单
+==================
+本小节将介绍如何创建一个从用户那搜集数据的表单页面。该页将显示一个包含 name 输入框和 email 输入框的表单。当搜集完这两部分信息后，页面将会显示用户输入的信息。
+为了实现这个目标，除了创建一个[操作](structure-controllers.md)和两个[视图](structure-views)外，你还需要创建一个[模型](structure-models.md)。
+贯穿整个小节，你将会学到：
+* 创建一个[模型](structure-models.md)表示用户通过表单输入的数据
+* 声明规则去验证输入的数据
+* 在[视图](structure-views.md)中生成一个 HTML 表单
+创建模型 <a name="creating-model"></a>
+----------------
+模型类 `EntryForm` 代表从用户那请求的数据，该类如下所示并存储在 `models/EntryForm.php` 文件中。请参考[类自动加载](concept-autoloading.md)小节获取更多关于类命名约定的介绍。
+```php
+<?php
+namespace app\models;
+use yii\base\Model;
+class EntryForm extends Model
+{
+    public $name;
+    public $email;
+    public function rules()
+    {
+        return [
+            [['name', 'email'], 'required'],
+            ['email', 'email'],
+        ];
+    }
+}
+```
+该类继承自 [[yii\base\Model]]，Yii 提供的一个基类，通常用来表示数据。
+> 补充：[[yii\base\Model]] 被用于普通模型类的父类并与数据表**无关**。[[yii\db\ActiveRecord]] 通常是普通模型类的父类但与数据表有关联（译者注：[[yii\db\ActiveRecord]] 类其实也是继承自 [[yii\base\Model]]，增加了数据库处理）。
+`EntryForm` 类包含 `name` 和 `email` 两个公共成员，用来储存用户输入的数据。它还包含一个名为 `rules()` 的方法，用来返回数据验证规则的集合。上面声明的验证规则表示：
+* `name` 和 `email` 值都是必须的
+* `mail` 的值必须满足 email 地址验证
+如果你有一个从用户那搜集了数据的 `EntryForm` 对象，你可以调用它的 [[yii\base\Model::validate()|validate()]] 方法触发数据验证。如果有数据验证失败，将把 [[yii\base\Model::hasErrors|hasErrors]] 属性设为 ture，想要知道具体发生什么错误就调用 [[yii\base\Model::getErrors|getErrors]]。
+```php
+<?php
+$model = new EntryForm();
+$model->name = 'Qiang';
+$model->email = 'bad';
+if ($model->validate()) {
+    // 验证成功！
+} else {
+    // 失败！
+    // 使用 $model->getErrors() 获取错误详情
+}
+```
+创建操作 <a name="creating-action"></a>
+------------------
+下面你得在 `site` 控制器中创建一个 `entry` 操作用于新建的模型。操作的创建和使用已经在[说一声你好](start-hello.md)小节中解释了。
+```php
+<?php
+namespace app\controllers;
+use Yii;
+use yii\web\Controller;
+use app\models\EntryForm;
+class SiteController extends Controller
+{
+    // ...其它代码...
+    public function actionEntry()
+    {
+        $model = new EntryForm;
+        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
+            // 验证 $model 收到的数据
+            // 做些有意义的事 ...
+            return $this->render('entry-confirm', ['model' => $model]);
+        } else {
+            // 无论是初始化显示还是数据验证错误
+            return $this->render('entry', ['model' => $model]);
+        }
+    }
+}
+```
+该操作首先创建了一个 `EntryForm` 对象。然后尝试从 `$_POST` 搜集用户提交的数据，由 Yii 的 [[yii\web\Request::post()]] 方法负责搜集。如果模型被成功填充数据（也就是说用户已经提交了 HTML 表单），操作将调用 [[yii\base\Model::validate()|validate()]] 去确保用户提交的是有效数据。
+> 补充：表达式 `Yii::$app` 代表[应用](structure-applications.md)实例，它是一个全局可访问的单例。同时它也是一个[服务定位器](concept-service-locator.md)，能提供 `request`，`response`，`db` 等等特定功能的组件。在上面的代码里就是使用 `request` 组件来访问应用实例收到的 `$_POST` 数据。
+用户提交表单后，操作将会渲染一个名为 `entry-confirm` 的视图去确认用户输入的数据。如果没填表单就提交，或数据包含错误（译者：如 email 格式不对），`entry` 视图将会渲染输出，连同表单一起输出的还有验证错误的信息。
+> 注意：在这个简单例子里我们只是呈现了有效数据的确认页面。实践中你应该考虑使用 [[yii\web\Controller::refresh()|refresh()]] 或 [[yii\web\Controller::redirect()|redirect()]] 去避免[表单重复提交问题](http://en.wikipedia.org/wiki/Post/Redirect/Get)。
+创建视图 <a name="creating-views"></a>
+--------------
+最后创建两个视图文件 `entry-confirm` 和 `entry`。他们会被刚才创建的 `entry` 操作渲染。
+`entry-confirm` 视图简单地显示提交的 name 和 email 数据。视图文件保存在 `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>
+```
+`entry` 视图显示一个 HTML 表单。视图文件保存在 `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(); ?>
+```
+视图使用了一个功能强大的[小部件](structure-widgets.md) [[yii\widgets\ActiveForm|ActiveForm]] 去生成 HTML 表单。其中的 `begin()` 和 `end()` 分别用来渲染表单的开始和关闭标签。在这两个方法之间使用了 [[yii\widgets\ActiveForm::field()|field()]] 方法去创建输入框。第一个输入框用于 “name”，第二个输入框用于 “email”。之后使用 [[yii\helpers\Html::submitButton()]] 方法生成提交按钮。
+尝试下 <a name="trying-it-out"></a>
+-------------
+用浏览器访问下面的 URL 看它能否工作：
+```
+http://hostname/index.php?r=site/entry
+```
+你会看到一个包含两个输入框的表单的页面。每个输入框的前面都有一个标签指明应该输入的数据类型。如果什么都不填就点击提交按钮，或填入格式不正确的 email 地址，你将会看到在对应的输入框下显示错误信息。
+![验证错误的表单](images/start-form-validation.png)
+输入有效的 name 和 email 信息并提交后，你将会看到一个显示你所提交数据的确认页面。
+![输入数据的确认页](images/start-entry-confirmation.png)
+### 效果说明 <a name="magic-explained"></a>
+你可能会好奇 HTML 表单暗地里是如何工作的呢，看起来它可以为每个输入框显示文字标签，而当你没输入正确的信息时又不需要刷新页面就能给出错误提示，似乎有些神奇。
+是的，其实数据首先由客户端 JavaScript 脚本验证，然后才会提交给服务器通过 PHP 验证。[[yii\widgets\ActiveForm]] 足够智能到把你在 `EntryForm` 模型中声明的验证规则转化成客户端 JavaScript 脚本去执行验证。如果用户浏览器禁用了 JavaScript， 服务器端仍然会像 `actionEntry()` 方法里这样验证一遍数据。这保证了任何情况下用户提交的数据都是有效的。
+> 警告：客户端验证是提高用户体验的手段。无论它是否正常启用，服务端验证则都是必须的，请不要忽略它。
+输入框的文字标签是 `field()` 方法生成的，内容就是模型中该数据的属性名。例如模型中的 `name` 属性生成的标签就是 `Name`。
+你可以在视图中自定义标签：
+```php
+<?= $form->field($model, 'name')->label('自定义 Name') ?>
+<?= $form->field($model, 'email')->label('自定义 Email') ?>
+```
+> 补充：Yii 提供了相当多类似的小部件去帮你生成复杂且动态的视图。在后面你还会了解到自己写小部件是多么简单。你可能会把自己的很多视图代码转化成小部件以提高重用，加快开发效率。
+总结 <a name="summary"></a>
+-------
+本小节指南中你接触了 MVC 设计模式的每个部分。你学到了如何创建一个模型代表用户数据并验证它的有效性。
+你还学到了如何从用户那获取数据并在浏览器上回显给用户。这本来是开发应用的过程中比较耗时的任务，好在 Yii 提供了强大的小部件让它变得如此简单。
+下一小节你将学习如何使用数据库，几乎每个应用都需要数据库。
--- a/docs/guide-zh-CN/start-gii.md
+++ b/docs/guide-zh-CN/start-gii.md
+使用 Gii 生成代码
+========================
+本小节将介绍如何使用 [Gii](tool-gii.md) 去自动生成 Web 站点常用功能的代码。使用 Gii 生成代码非常简单，只要按照 Gii 页面上的介绍输入正确的信息即可。
+贯穿本小节，你将会学到：
+* 在你的应用中开启 Gii
+* 使用 Gii 去生成活动记录类
+* 使用 Gii 去生成数据表操作的增查改删（CRUD）代码
+* 自定义 Gii 生成的代码
+开始 Gii <a name="starting-gii"></a>
+------------
+[Gii](tool-gii.md) 是 Yii 中的一个[模块](structure-modules.md)。你可以通过配置应用的 [[yii\base\Application::modules|modules]] 属性开启它。通常来讲在 `config/web.php` 文件中会有以下配置代码：
+```php
+$config = [ ... ];
+if (YII_ENV_DEV) {
+    $config['bootstrap'][] = 'gii';
+    $config['modules']['gii'] = 'yii\gii\Module';
+}
+```
+这段配置的意思是如果当前是[开发环境](concept-configurations.md#environment-constants)，应用会包含 `gii` 模块，模块类是 [[yii\gii\Module]]。
+如果你检查应用的[入口脚本](structure-entry-scripts.md) `web/index.php`，将看到这行代码将 `YII_ENV_DEV` 设为 true：
+```php
+defined('YII_ENV') or define('YII_ENV', 'dev');
+```
+代码设置应用处于开发模式下，按照上面的配置会打开 Gii 模块。你可以直接通过 URL 访问 Gii：
+```
+http://hostname/index.php?r=gii
+```
+![Gii](images/start-gii.png)
+生成活动记录类 <a name="generating-ar"></a>
+---------------------------------
+选择 “Model Generator” （点击 Gii 首页的链接）去生成活动记录类。并像这样填写表单：
+* Table Name: `country`
+* Model Class: `Country`
+![模型生成器](images/start-gii-model.png)
+然后点击 “Preview” 按钮。你会看到 `models/Country.php` 被列在将要生成的文件列表中。可以点击文件名预览内容。
+如果你已经创建过同样的文件，使用 Gii 可以覆写它，点击文件名旁边的 `diff` 能查看现有文件与将要生成的文件的内容区别。
+![模型生成器预览](images/start-gii-model-preview.png)
+想要覆写已存在文件，选中 “overwrite” 下的复选框然后点击 “Generator”。如果是新文件，只点击 “Generator” 就好。
+接下来你会看到一个包含已生成文件的说明页面。如果生成过程中覆写过文件，还会有一条信息说明代码是重新生成覆盖的。
+生成 CRUD 代码 <a name="generating-crud"></a>
+--------------------
+CRUD 代表增，查，改，删操作，这是绝大多数 Web 站点常用的数据处理方式。选择 Gii 中的 “CRUD Generator” （点击 Gii 首页的链接）去创建 CRUD 功能。之前的 “country” 例子需要像这样填写表单：
+* Model Class: `app\models\Country`
+* Search Model Class: `app\models\CountrySearch`
+* Controller Class: `app\controllers\CountryController`
+![CRUD 生成器](images/start-gii-crud.png)
+然后点击 “Preview” 按钮。你会看到下述将要生成的文件列表。
+[[NEED THE IMAGE HERE / 等待官方补充图片]]
+如果你之前创建过 `controllers/CountryController.php` 和 `views/country/index.php` 文件（在指南的使用数据库小节），选中 “overwrite” 下的复选框覆写它们（之前的文件没能全部支持 CRUD）。
+尝试下<a name="trying-it-out"></a>
+-------------
+用浏览器访问下面的 URL 查看生成代码的运行：
+```
+http://hostname/index.php?r=country/index
+```
+可以看到一个栅格显示着从数据表中获取的国家数据。支持在列头对数据进行排序，输入筛选条件进行筛选。
+可以浏览详情，编辑，或删除栅格中的每个国家。还可以点击栅格上方的 “Create Country” 按钮通过表单创建新国家。
+![国家的数据栅格](images/start-gii-country-grid.png)
+![编辑一个国家](images/start-gii-country-update.png)
+下面列出由 Gii 生成的文件，以便你也许想研习功能和实现，或修改它们。
+* 控制器：`controllers/CountryController.php`
+* 模型：`models/Country.php` 和 `models/CountrySearch.php`
+* 视图：`views/country/*.php`
+> 补充：Gii 被设计成高度可定制和可扩展的代码生成工具。使用它可以大幅提高应用开发速度。请参考 [Gii](tool-gii.md) 小节了解更多内容。
+总结 <a name="summary"></a>
+-------
+本小节学习了如何使用 Gii 去生成为数据表中数据实现完整 CRUD 功能的代码。
--- a/docs/guide-zh-CN/start-looking-ahead.md
+++ b/docs/guide-zh-CN/start-looking-ahead.md
+更上一层楼
+=============
+通篇阅读完整个“入门”章节，你就完成了一个完整 Yii 应用的创建。在此过程中你学到了如何实现一些常用功能，例如通过 HTML 表单从用户那获取数据，从数据库中获取数据并以分页形式显示。你还学到了如何通过 [Gii](tool-gii.md) 去自动生成代码。使用 Gii 生成代码把 Web 开发中多数繁杂的过程转化为仅仅填写几个表单就行。
+本小节将介绍一些有助于更好使用 Yii 的资源：
+* 文档
+    - 权威指南：
+      顾名思义，指南详细描述了 Yii 的工作原理并提供了如何使用它的常规引导。这是最重要的 Yii 辅助资料，强烈建议在你开始写 Yii 代码之前阅读。
+    - 类参考手册：
+      描述了 Yii 中每个类的用法。在编码过程中这极为有用，能够帮你理清某个特定类，方法，和属性的用法。类参考手册最好在整个框架的语境下去理解。
+    - Wiki 文章：
+      Wiki 文章是 Yii 用户在其自身经验基础上分享出来的。大多数是使用教程或如何使用 Yii 解决特定问题。虽然这些文章质量可能并不如权威指南，但它们往往覆盖了更广泛的话题，并常常提供解决方案，所以它们也很有用。
+    - 书籍
+* [扩展](http://www.yiiframework.com/extensions/):
+  Yii 拥有数以千计用户提供的扩展，这些扩展能非常方便的插入到应用中，使你的应用开发过程更加方便快捷。
+* 社区
+    - [官方论坛](http://www.yiiframework.com/forum/)
+    - [GitHub](https://github.com/yiisoft/yii2)
+    - [Facebook](https://www.facebook.com/groups/yiitalk/)
+    - [Twitter](https://twitter.com/yiiframework)
+    - [LinkedIn](https://www.linkedin.com/groups/yii-framework-1483367)
--- a/docs/guide/start-looking-head.md
+++ b/docs/guide/start-looking-head.md