Skip to content

Y
yii2
Commit 3be0350b by AbrahamGreyson
Options

Guide-zh-CN getting started part adjusted words.

parent 6c2d759b
Showing with 39 additions and 39 deletions
docs/guide-zh-CN/start-databases.md
使用数据库
======================
本小节将介绍如何如何创建一个从数据表 `country` 中获取国家数据并显示出来的页面。为了实现这个目标，你将会配置一个数据库连接，创建一个[活动记录](db-active-record.md)类，并且创建一个[操作](structure-controllers.md)及一个[视图](structure-views.md)。
本章节将介绍如何如何创建一个从数据表 `country` 中获取国家数据并显示出来的页面。为了实现这个目标，你将会配置一个数据库连接，创建一个[活动记录](db-active-record.md)类，并且创建一个[操作](structure-controllers.md)及一个[视图](structure-views.md)。
贯穿整个小节，你将会学到：
贯穿整个章节，你将会学到：
* 配置一个数据库连接
* 定义一个活动记录类
* 使用活动记录从数据库中查询数据
* 以分页方式在视图中显示数据
请注意，为了掌握本小节你应该具备最基本的数据库知识和使用经验。尤其是你应该知道如何创建数据库，如何通过数据库终端执行 SQL 语句。
请注意，为了掌握本章你应该具备最基本的数据库知识和使用经验。尤其是应该知道如何创建数据库，如何通过数据库终端执行 SQL 语句。
准备数据库 <a name="preparing-database"></a>
--------------------
首先创建一个名为 `yii2basic` 的数据库，你的应用将从这个数据库中获取数据。你可以创建 SQLite，MySQL，PostregSQL，MSSQL 或 Oracle 数据库，Yii 内置多种数据库支持。简单起见后面的内容将以 MySQL 为例做演示。
首先创建一个名为 `yii2basic` 的数据库，应用将从这个数据库中获取数据。你可以创建 SQLite，MySQL，PostregSQL，MSSQL 或 Oracle 数据库，Yii 内置多种数据库支持。简单起见后面的内容将以 MySQL 为例做演示。
然后在数据库中创建一个名为 `country` 的表并插入简单的数据。可以执行下面的语句：
......@@ -64,7 +64,7 @@ return [
上面配置的数据库连接可以在应用中通过 `Yii::$app->db` 访问。
> 补充：`config/db.php` 将被包含在应用配置文件 `config/web.php` 中，后者指定了整个[应用](structure-applications.md)如何初始化。请参考[配置](concept-configurations.md)小节了解更多信息。
> 补充：`config/db.php` 将被包含在应用配置文件 `config/web.php` 中，后者指定了整个[应用](structure-applications.md)如何初始化。请参考[配置](concept-configurations.md)章节了解更多信息。
创建活动记录 <a name="creating-active-record"></a>
......@@ -86,9 +86,9 @@ class Country extends ActiveRecord
这个 `Country` 类继承自 [[yii\db\ActiveRecord]]。你不用在里面写任何代码。只需要像现在这样，Yii 就能根据类名去猜测对应的数据表名。
> 补充：如果类名和数据表名不能直接对应，你可以重写 [[yii\db\ActiveRecord::tableName()|tableName()]] 方法去显式指定相关表名。
> 补充：如果类名和数据表名不能直接对应，可以重写 [[yii\db\ActiveRecord::tableName()|tableName()]] 方法去显式指定相关表名。
使用 `Country` 类你可以很容易地操作 `country` 表数据，就像这段代码：
使用 `Country` 类可以很容易地操作 `country` 表数据，就像这段代码：
```php
use app\models\Country;
......@@ -107,7 +107,7 @@ $country->name = 'U.S.A.';
$country->save();
```
> 补充：活动记录是面向对象、功能强大的访问和操作数据库数据的方式。你可以在[活动记录](db-active-record.md)小节了解更多信息。除此之外你还可以使用另一种更原生的称做[数据访问对象](db-dao)的方法操作数据库数据。
> 补充：活动记录是面向对象、功能强大的访问和操作数据库数据的方式。你可以在[活动记录](db-active-record.md)章节了解更多信息。除此之外你还可以使用另一种更原生的称做[数据访问对象](db-dao)的方法操作数据库数据。
创建操作 <a name="creating-action"></a>
......@@ -210,6 +210,6 @@ http://hostname/index.php?r=country/index&page=2
总结 <a name="summary"></a>
-------
本小节中你学到了如何使用数据库。你还学到了如何取出并使用 [[yii\data\Pagination]] 和 [[yii\widgets\LinkPager]] 显示数据。
本章节中你学到了如何使用数据库。你还学到了如何取出并使用 [[yii\data\Pagination]] 和 [[yii\widgets\LinkPager]] 显示数据。
下一小节中你会学到如何使用 Yii 中强大的代码生成器 [Gii](tool-gii.md)，去帮助你实现一些常用的功能需求，例如增查改善（CRUD）数据表中的数据。事实上你之前所写的代码全部都可以由 Gii 自动生成：）
\ No newline at end of file
下一章中你会学到如何使用 Yii 中强大的代码生成器 [Gii](tool-gii.md)，去帮助你实现一些常用的功能需求，例如增查改删（CRUD）数据表中的数据。事实上你之前所写的代码全部都可以由 Gii 自动生成。
\ No newline at end of file
docs/guide-zh-CN/start-forms.md
使用表单
==================
本小节将介绍如何创建一个从用户那搜集数据的表单页面。该页将显示一个包含 name 输入框和 email 输入框的表单。当搜集完这两部分信息后，页面将会显示用户输入的信息。
本章节将介绍如何创建一个从用户那搜集数据的表单页。该页将显示一个包含 name 输入框和 email 输入框的表单。当搜集完这两部分信息后，页面将会显示用户输入的信息。
为了实现这个目标，除了创建一个[操作](structure-controllers.md)和两个[视图](structure-views)外，你还需要创建一个[模型](structure-models.md)。
为了实现这个目标，除了创建一个[操作](structure-controllers.md)和两个[视图](structure-views)外，还需要创建一个[模型](structure-models.md)。
贯穿整个小节，你将会学到：
* 创建一个[模型](structure-models.md)表示用户通过表单输入的数据
* 创建一个[模型](structure-models.md)代表用户通过表单输入的数据
* 声明规则去验证输入的数据
* 在[视图](structure-views.md)中生成一个 HTML 表单
......@@ -15,7 +15,7 @@
创建模型 <a name="creating-model"></a>
----------------
模型类 `EntryForm` 代表从用户那请求的数据，该类如下所示并存储在 `models/EntryForm.php` 文件中。请参考[类自动加载](concept-autoloading.md)小节获取更多关于类命名约定的介绍。
模型类 `EntryForm` 代表从用户那请求的数据，该类如下所示并存储在 `models/EntryForm.php` 文件中。请参考[类自动加载](concept-autoloading.md)章节获取更多关于类命名约定的介绍。
```php
<?php
......@@ -48,7 +48,7 @@ class EntryForm extends Model
* `name` 和 `email` 值都是必须的
* `mail` 的值必须满足 email 地址验证
如果你有一个从用户那搜集了数据的 `EntryForm` 对象，你可以调用它的 [[yii\base\Model::validate()|validate()]] 方法触发数据验证。如果有数据验证失败，将把 [[yii\base\Model::hasErrors|hasErrors]] 属性设为 ture，想要知道具体发生什么错误就调用 [[yii\base\Model::getErrors|getErrors]]。
如果你有一个从用户那搜集数据的 `EntryForm` 对象，你可以调用它的 [[yii\base\Model::validate()|validate()]] 方法触发数据验证。如果有数据验证失败，将把 [[yii\base\Model::hasErrors|hasErrors]] 属性设为 ture，想要知道具体发生什么错误就调用 [[yii\base\Model::getErrors|getErrors]]。
```php
<?php
......@@ -104,7 +104,7 @@ class SiteController extends Controller
> 补充：表达式 `Yii::$app` 代表[应用](structure-applications.md)实例，它是一个全局可访问的单例。同时它也是一个[服务定位器](concept-service-locator.md)，能提供 `request`，`response`，`db` 等等特定功能的组件。在上面的代码里就是使用 `request` 组件来访问应用实例收到的 `$_POST` 数据。
用户提交表单后，操作将会渲染一个名为 `entry-confirm` 的视图去确认用户输入的数据。如果没填表单就提交，或数据包含错误（译者：如 email 格式不对），`entry` 视图将会渲染输出，连同表单一起输出的还有验证错误的信息。
用户提交表单后，操作将会渲染一个名为 `entry-confirm` 的视图去确认用户输入的数据。如果没填表单就提交，或数据包含错误（译者：如 email 格式不对），`entry` 视图将会渲染输出，连同表单一起输出的还有验证错误的详细信息。
> 注意：在这个简单例子里我们只是呈现了有效数据的确认页面。实践中你应该考虑使用 [[yii\web\Controller::refresh()|refresh()]] 或 [[yii\web\Controller::redirect()|redirect()]] 去避免[表单重复提交问题](http://en.wikipedia.org/wiki/Post/Redirect/Get)。
......@@ -160,11 +160,11 @@ use yii\widgets\ActiveForm;
http://hostname/index.php?r=site/entry
```
你会看到一个包含两个输入框的表单的页面。每个输入框的前面都有一个标签指明应该输入的数据类型。如果什么都不填就点击提交按钮，或填入格式不正确的 email 地址，你将会看到在对应的输入框下显示错误信息。
你会看到一个包含两个输入框的表单的页面。每个输入框的前面都有一个标签指明应该输入的数据类型。如果什么都不填就点击提交按钮，或填入格式不正确的 email 地址，将会看到在对应的输入框下显示错误信息。
![验证错误的表单](images/start-form-validation.png)
输入有效的 name 和 email 信息并提交后，你将会看到一个显示你所提交数据的确认页面。
输入有效的 name 和 email 信息并提交后，将会看到一个显示你所提交数据的确认页面。
![输入数据的确认页](images/start-entry-confirmation.png)
......@@ -193,8 +193,8 @@ http://hostname/index.php?r=site/entry
总结 <a name="summary"></a>
-------
本小节指南中你接触了 MVC 设计模式的每个部分。你学到了如何创建一个模型代表用户数据并验证它的有效性。
本章节指南中你接触了 MVC 设计模式的每个部分。学到了如何创建一个模型代表用户数据并验证它的有效性。
你还学到了如何从用户那获取数据并在浏览器上回显给用户。这本来是开发应用的过程中比较耗时的任务，好在 Yii 提供了强大的小部件让它变得如此简单。
下一小节你将学习如何使用数据库，几乎每个应用都需要数据库。
下一章你将学习如何使用数据库，几乎每个应用都需要数据库。
docs/guide-zh-CN/start-gii.md
使用 Gii 生成代码
========================
本小节将介绍如何使用 [Gii](tool-gii.md) 去自动生成 Web 站点常用功能的代码。使用 Gii 生成代码非常简单，只要按照 Gii 页面上的介绍输入正确的信息即可。
本章节将介绍如何使用 [Gii](tool-gii.md) 去自动生成 Web 站点常用功能的代码。使用 Gii 生成代码非常简单，只要按照 Gii 页面上的介绍输入正确的信息即可。
贯穿本小节，你将会学到：
贯穿本章节，你将会学到：
* 在你的应用中开启 Gii
* 使用 Gii 去生成活动记录类
......@@ -14,7 +14,7 @@
开始 Gii <a name="starting-gii"></a>
------------
[Gii](tool-gii.md) 是 Yii 中的一个[模块](structure-modules.md)。你可以通过配置应用的 [[yii\base\Application::modules|modules]] 属性开启它。通常来讲在 `config/web.php` 文件中会有以下配置代码：
[Gii](tool-gii.md) 是 Yii 中的一个[模块](structure-modules.md)。可以通过配置应用的 [[yii\base\Application::modules|modules]] 属性开启它。通常来讲在 `config/web.php` 文件中会有以下配置代码：
```php
$config = [ ... ];
......@@ -98,7 +98,7 @@ http://hostname/index.php?r=country/index
![编辑一个国家](images/start-gii-country-update.png)
下面列出由 Gii 生成的文件，以便你也许想研习功能和实现，或修改它们。
下面列出由 Gii 生成的文件，以便你研习功能和实现，或修改它们。
* 控制器：`controllers/CountryController.php`
* 模型：`models/Country.php` 和 `models/CountrySearch.php`
......@@ -110,4 +110,4 @@ http://hostname/index.php?r=country/index
总结 <a name="summary"></a>
-------
本小节学习了如何使用 Gii 去生成为数据表中数据实现完整 CRUD 功能的代码。
本章学习了如何使用 Gii 去生成为数据表中数据实现完整 CRUD 功能的代码。
docs/guide-zh-CN/start-hello.md
说声 Hello
============
本小节描述如何在你的应用中创建一个新的 “Hello” 页面。为了做到这点，你将会创建一个[操作](structure-controllers.md#creating-actions)和一个[视图](structure-views.md)：
本章节描述了如何在你的应用中创建一个新的 “Hello” 页面。为了做到这点，将会创建一个[操作](structure-controllers.md#creating-actions)和一个[视图](structure-views.md)：
* 应用将会分派页面请求给操作
* 操作将会依次渲染视图呈现 “Hello” 给最终用户
贯穿整个小节，你将会掌握三件事：
贯穿整个章节，你将会掌握三件事：
1. 如何创建一个[操作](structure-controllers.md)去响应请求，
2. 如何创建一个[视图](structure-views.md)去构造响应内容，
......@@ -16,9 +16,9 @@
创建操作 <a name="creating-action"></a>
------------------
为了说 “Hello”，你需要创建一个 `say` [操作](structure-controllers.md#creating-actions)，从请求中接收 `message` 参数并显示给最终用户。如果请求没有提供 `message` 参数，操作将显示默认参数 “Hello”。
为了说 “Hello”，需要创建一个 `say` [操作](structure-controllers.md#creating-actions)，从请求中接收 `message` 参数并显示给最终用户。如果请求没有提供 `message` 参数，操作将显示默认参数 “Hello”。
> 补充：[操作](structure-controllers.md#creating-actions)是最终用户可以直接访问并执行的对象。操作被组织在[控制器](structure-controllers.md)中。一个操作的执行结果就是最终用户将会收到的响应内容。
> 补充：[操作](structure-controllers.md#creating-actions)是最终用户可以直接访问并执行的对象。操作被组织在[控制器](structure-controllers.md)中。一个操作的执行结果就是最终用户收到的响应内容。
操作必须声明在[控制器](structure-controllers.md)中。为了简单起见，你可以直接在 `SiteController` 控制器里声明 `say` 操作。这个控制器是由文件 `controllers/SiteController.php` 定义的。以下是一个操作的声明：
......@@ -44,7 +44,7 @@ class SiteController extends Controller
涉及到给操作命名时，你应该理解 Yii 如何处理操作 ID。操作 ID 总是被以小写处理，如果一个操作 ID 由多个单词组成，单词之间将由连字符连接（如 `create-comment`）。操作 ID 映射为方法名时移除了连字符，将每个单词首字母大写，并加上 `action` 前缀。 例子：操作 ID `create-comment` 相当于方法名 `actionCreateComment`。
上述代码中的操作方法接受一个参数 `$message`，它的默认值是 `“Hello”`（就像你设置其它 PHP 函数或方法的默认值一样）。当应用接收到请求并确定由 `say` 操作来响应请求时，应用将从请求的参数中寻找对应值传入进来。换句话说，如果请求包含一个 `message` 参数，它的值是 `“Goodybye”`， 操作方法中的 `$message` 变量也将被填充为 `“Goodbye”`。
上述代码中的操作方法接受一个参数 `$message`，它的默认值是 `“Hello”`（就像你设置 PHP 中其它函数或方法的默认值一样）。当应用接收到请求并确定由 `say` 操作来响应请求时，应用将从请求的参数中寻找对应值传入进来。换句话说，如果请求包含一个 `message` 参数，它的值是 `“Goodybye”`， 操作方法中的 `$message` 变量也将被填充为 `“Goodbye”`。
在操作方法中，[[yii\web\Controller::render()|render()]] 被用来渲染一个名为 `say` 的[视图](structure-views.md)文件。 `message` 参数也被传入视图，这样就可以在里面使用。操作方法会返回渲染结果。结果会被应用接收并显示给最终用户的浏览器（作为整页 HTML 的一部分）。
......@@ -63,7 +63,7 @@ use yii\helpers\Html;
`say` 视图应该存为 `views/site/say.php` 文件。当一个操作中调用了 [[yii\web\Controller::render()|render()]] 方法时，它将会按 `views/控制器 ID/视图名.php` 路径加载 PHP 文件。
注意以上代码，`message` 参数在输出之前被 [[yii\helpers\Html::encode()|HTML-encoded]] 方法处理过。这非常有必要，当参数来自于最终用户时，参数中的恶意 JavaScript 代码会导致[跨站脚本（XSS）攻击](http://en.wikipedia.org/wiki/Cross-site_scripting)。
注意以上代码，`message` 参数在输出之前被 [[yii\helpers\Html::encode()|HTML-encoded]] 方法处理过。这很有必要，当参数来自于最终用户时，参数中可能隐含的恶意 JavaScript 代码会导致[跨站脚本（XSS）攻击](http://en.wikipedia.org/wiki/Cross-site_scripting)。
当然了，你大概会在 `say` 视图里放入更多内容。内容可以由 HTML 标签，纯文本，甚至 PHP 语句组成。实际上 `say` 视图就是一个由 [[yii\web\Controller::render()|render()]] 执行的 PHP 脚本。视图脚本输出的内容将会作为响应结果返回给应用。应用将依次输出结果给最终用户。
......@@ -85,7 +85,7 @@ http://hostname/index.php?r=site/say&message=Hello+World
> 补充：新页面和其它页面使用同样的头部和尾部是因为 [[yii\web\Controller::render()|render()]] 方法会自动把 `say` 视图执行的结果嵌入称为[布局](structure-views.md#layouts)的文件中，本例中是 `views/layouts/main.php`。
上面 URL 中的参数 `r` 需要更多解释。它代表[路由](runtime-routing.md)，整个应用级的，指向特定操作的独立 ID。路由格式是 `控制器 ID/操作 ID`。应用接受请求的时候会检查参数，使用控制器 ID 去确定哪个控制器应该被用来处理请求。然后相应控制器将使用操作 ID 去确定哪个操作方法将被用来做具体工作。上述例子中，路由 `site/say` 将被解析至 `SiteController` 控制器和其中的 `say` 操作。因此 `SiteController::actionSay()` 方法将被调用处理请求。
上面 URL 中的参数 `r` 需要更多解释。它代表[路由](runtime-routing.md)，是整个应用级的，指向特定操作的独立 ID。路由格式是 `控制器 ID/操作 ID`。应用接受请求的时候会检查参数，使用控制器 ID 去确定哪个控制器应该被用来处理请求。然后相应控制器将使用操作 ID 去确定哪个操作方法将被用来做具体工作。上述例子中，路由 `site/say` 将被解析至 `SiteController` 控制器和其中的 `say` 操作。因此 `SiteController::actionSay()` 方法将被调用处理请求。
> 补充：与操作一样，一个应用中控制器同样有唯一的 ID。控制器 ID 和操作 ID 使用同样的命名规则。控制器的类名源自于控制器 ID，移除了连字符，每个单词首字母大写，并加上 `Controller` 后缀。例子：控制器 ID `post-comment` 相当于控制器类名 `PostCommentController`。
......@@ -93,8 +93,8 @@ http://hostname/index.php?r=site/say&message=Hello+World
总结 <a name="summary"></a>
-------
在本小节你已经接触了 MVC 设计模式中的控制器和视图部分。你创建了一个操作作为控制器的一部分去处理特定请求。然后你又创建了一个视图去构造响应内容。在这个小例子中，没有模型调用，唯一涉及到数据的地方是 `message` 参数。
通过本章节你接触了 MVC 设计模式中的控制器和视图部分。创建了一个操作作为控制器的一部分去处理特定请求。然后又创建了一个视图去构造响应内容。在这个小例子中，没有模型调用，唯一涉及到数据的地方是 `message` 参数。
你同样学习了 Yii 路由的相关内容，它是用户请求与控制器操作之间的桥梁。
在下一节，你将学习如何创建一个模型，以及添加一个包含 HTML 表单的页面。
下一章，你将学习如何创建一个模型，以及添加一个包含 HTML 表单的页面。
docs/guide-zh-CN/start-looking-ahead.md
更上一层楼
=============
通篇阅读完整个“入门”章节，你就完成了一个完整 Yii 应用的创建。在此过程中你学到了如何实现一些常用功能，例如通过 HTML 表单从用户那获取数据，从数据库中获取数据并以分页形式显示。你还学到了如何通过 [Gii](tool-gii.md) 去自动生成代码。使用 Gii 生成代码把 Web 开发中多数繁杂的过程转化为仅仅填写几个表单就行。
通篇阅读完整个“入门”板块，你就完成了一个完整 Yii 应用的创建。在此过程中你学到了如何实现一些常用功能，例如通过 HTML 表单从用户那获取数据，从数据库中获取数据并以分页形式显示。你还学到了如何通过 [Gii](tool-gii.md) 去自动生成代码。使用 Gii 生成代码把 Web 开发中多数繁杂的过程转化为仅仅填写几个表单就行。
本小节将介绍一些有助于更好使用 Yii 的资源：
本章节将介绍一些有助于更好使用 Yii 的资源：
* 文档
- 权威指南：
顾名思义，指南详细描述了 Yii 的工作原理并提供了如何使用它的常规引导。这是最重要的 Yii 辅助资料，强烈建议在你开始写 Yii 代码之前阅读。
顾名思义，指南详细描述了 Yii 的工作原理并提供了如何使用它的常规引导。这是最重要的 Yii 辅助资料，强烈建议在开始写 Yii 代码之前阅读。
- 类参考手册：
描述了 Yii 中每个类的用法。在编码过程中这极为有用，能够帮你理清某个特定类，方法，和属性的用法。类参考手册最好在整个框架的语境下去理解。
- Wiki 文章：
......
docs/guide-zh-CN/start-workflow.md
......@@ -3,7 +3,7 @@
安装 Yii 后，就有了一个运行中的 Yii 应用，根据配置的不同，可以通过 `http://hostname/basic/web/index.php` 或 `http://hostname/index.php` 访问。本章节将介绍应用的内建功能，如何组织代码，以及一般情况下应用如何处理请求。
> 补充：为简单起见，在整个“入门”部分都假定你已经把 `basic/web` 设为 Web 服务器根目录并配置完毕，你访问应用的地址会是 `http://lostname/index.php` 或类似的。请按需调整 URL。
> 补充：为简单起见，在整个“入门”板块都假定你已经把 `basic/web` 设为 Web 服务器根目录并配置完毕，你访问应用的地址会是 `http://lostname/index.php` 或类似的。请按需调整 URL。
功能 <a name="functionality"></a>
-------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment