From f39c105067e08fe416f86d0a415f5475ce66ba17 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?TZ=20=7C=20=E5=A4=A9=E7=8C=AA?= <atian25@qq.com>
Date: Wed, 29 Nov 2017 08:55:44 +0800
Subject: [PATCH] docs(view): use async (#1717)

---
 docs/source/zh-cn/advanced/view-plugin.md |  2 +-
 docs/source/zh-cn/core/view.md            | 88 ++++++++++++-----------
 2 files changed, 46 insertions(+), 44 deletions(-)

diff --git a/docs/source/zh-cn/advanced/view-plugin.md b/docs/source/zh-cn/advanced/view-plugin.md
index 878716622f..165c9f90b4 100644
--- a/docs/source/zh-cn/advanced/view-plugin.md
+++ b/docs/source/zh-cn/advanced/view-plugin.md
@@ -160,7 +160,7 @@ module.exports = class MyCustomView {
 }
 ```
 
-具体代码可[查看](https://github.com/eggjs/egg-view-nunjucks/blob/0433cadd3bc7a88e925b01bae08cc85c38a0af71/lib/view.js#L11)
+具体代码可[查看](https://github.com/eggjs/egg-view-nunjucks/blob/2ee5ee992cfd95bc0bb5b822fbd72a6778edb118/lib/view.js#L11)
 
 ### 安全相关
 
diff --git a/docs/source/zh-cn/core/view.md b/docs/source/zh-cn/core/view.md
index b3d9f6c5b1..b6a63e6b10 100644
--- a/docs/source/zh-cn/core/view.md
+++ b/docs/source/zh-cn/core/view.md
@@ -37,14 +37,14 @@ exports.nunjucks = {
 // config/config.default.js
 const path = require('path');
 module.exports = appInfo => {
-  return {
-    view: {
-      root: [
-        path.join(appInfo.baseDir, 'app/view'),
-        path.join(appInfo.baseDir, 'path/to/another'),
-      ].join(',')
-    }
-  }
+  const config = {};
+  config.view = {
+    root: [
+      path.join(appInfo.baseDir, 'app/view'),
+      path.join(appInfo.baseDir, 'path/to/another'),
+    ].join(',')
+  };
+  return config;
 };
 ```
 
@@ -66,10 +66,10 @@ module.exports = {
 };
 ```
 
-调用 render 渲染文件
+调用 render 渲染文件时，会根据上述配置的后缀名去寻找对应的模板引擎。
 
 ```js
-ctx.render('home.nj');
+await ctx.render('home.nj');
 ```
 
 必须配置文件后缀和模板引擎的映射，否则无法找到对应的模板引擎，但是可以使用 `defaultViewEngine` 做全局配置。
@@ -98,7 +98,7 @@ module.exports = {
 };
 
 // render app/view/home.nj
-ctx.render('home');
+await ctx.render('home');
 ```
 
 ## 渲染页面
@@ -111,66 +111,68 @@ ctx.render('home');
 
 ```js
 // {app_root}/app/controller/home.js
-module.exports = function* home(ctx){
-  const data = { name: 'egg' };
+class HomeController extends Controller {
+  async index() {
+    const data = { name: 'egg' };
 
-  // render a template, path relate to `app/view`
-  yield ctx.render('home/index.tpl', data);
+    // render a template, path relate to `app/view`
+    await ctx.render('home/index.tpl', data);
 
-  // or manually set render result to ctx.body
-  ctx.body = yield ctx.renderView('path/to/file.tpl', data);
+    // or manually set render result to ctx.body
+    ctx.body = await ctx.renderView('path/to/file.tpl', data);
 
-  // or render string directly
-  ctx.body = yield ctx.renderString('hi, {{ name }}', data, {
-    viewEngine: 'nunjucks',
-  });
-};
+    // or render string directly
+    ctx.body = await ctx.renderString('hi, {{ name }}', data, {
+      viewEngine: 'nunjucks',
+    });
+  }
+}
 ```
 
 当使用 `renderString` 时需要指定模板引擎，如果已经定义 `defaultViewEngine` 这里可以省略。
 
 ## Locals
 
-在渲染页面的过程中，我们通常需要一个变量来收集需要传递给模板的变量，在框架里面，我们提供了 `app.locals` 和 `this.locals`。
+在渲染页面的过程中，我们通常需要一个变量来收集需要传递给模板的变量，在框架里面，我们提供了 `app.locals` 和 `ctx.locals`。
 
 - `app.locals` 为全局的，一般在 `app.js` 里面配置全局变量。
-- `this.locals` 为单次请求的，会合并 `app.locals`。
+- `ctx.locals` 为单次请求的，会合并 `app.locals`。
 - 可以直接赋值对象，框架在对应的 setter 里面会自动 merge。
 
 ```js
-// `app.locals` 会合并到 `this.locals
-this.app.locals = { a: 1 };
-this.locals.b = 2;
-console.log(this.locals); // { a: 1, b: 2 }
+// `app.locals` 会合并到 `ctx.locals
+ctx.app.locals = { a: 1 };
+ctx.locals.b = 2;
+console.log(ctx.locals); // { a: 1, b: 2 }
 
-// 一次请求过程中，仅会在第一次使用 `this.locals` 时把 `app.locals` 合并进去。
-this.app.locals = { a: 2 };
-console.log(this.locals); // 上面已经合并过一次，故输出还是 { a: 1, b: 2 }
+// 一次请求过程中，仅会在第一次使用 `ctx.locals` 时把 `app.locals` 合并进去。
+ctx.app.locals = { a: 2 };
+console.log(ctx.locals); // 上面已经合并过一次，故输出还是 { a: 1, b: 2 }
 
 // 也可以直接赋值整个对象，不用担心会覆盖前面的值，我们通过 setter 做了自动合并。
-this.locals.c = 3;
-this.locals = { d: 4 };
-console.log(this.locals); // { a: 1, b: 2, c: 3, d: 4 }
+ctx.locals.c = 3;
+ctx.locals = { d: 4 };
+console.log(ctx.locals); // { a: 1, b: 2, c: 3, d: 4 }
 ```
 
-但在实际业务开发中，controller 中一般不会直接使用这 2 个对象，直接使用 `this.render(name, data)` 即可：
-- 框架会自动把 `data` 合并到 `this.locals`。
+但在实际业务开发中，controller 中一般不会直接使用这 2 个对象，直接使用 `ctx.render(name, data)` 即可：
+- 框架会自动把 `data` 合并到 `ctx.locals`。
 - 框架会自动注入 `ctx`, `request`, `helper` 方便使用。
 
 ```js
-this.app.locals = { appName: 'showcase' };
+ctx.app.locals = { appName: 'showcase' };
 const data = { user: 'egg' };
 
-// will auto merge `data` to `this.locals`, output: egg - showcase
-yield this.renderString('{{ name }} - {{ appName }}', data);
+// will auto merge `data` to `ctx.locals`, output: egg - showcase
+await ctx.renderString('{{ name }} - {{ appName }}', data);
 
 // helper, ctx, request will auto inject
-yield this.renderString('{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.baseDir) }}', data);
+await ctx.renderString('{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.baseDir) }}', data);
 ```
 
 注意：
-- **this.locals 有缓存，只在第一次访问 this.locals 时合并 app.locals。**
-- 原 Koa 中的 `context.state`，由于容易产生歧义，在框架中被覆盖为 locals，即 `this.state` 和 `this.locals` 等价，我们建议使用后者。
+- **ctx.locals 有缓存，只在第一次访问 ctx.locals 时合并 app.locals。**
+- 原 Koa 中的 `ctx.state`，由于容易产生歧义，在框架中被覆盖为 locals，即 `ctx.state` 和 `ctx.locals` 等价，我们建议使用后者。
 
 ## Helper
 
@@ -181,7 +183,7 @@ yield this.renderString('{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.ba
 exports.lowercaseFirst = str => str[0].toLowerCase() + str.substring(1);
 
 // app/controller/home.js
-yield this.renderString('{{ helper.lowercaseFirst(name) }}', data);
+await ctx.renderString('{{ helper.lowercaseFirst(name) }}', data);
 ```
 
 ## Security