diff --git a/docs/source/en/advanced/view-plugin.md b/docs/source/en/advanced/view-plugin.md index 9957735520..1e8bc28484 100644 --- a/docs/source/en/advanced/view-plugin.md +++ b/docs/source/en/advanced/view-plugin.md @@ -1 +1,181 @@ -this document is still waiting for translation, see [Chinese Version](/zh-cn/advanced/view-plugin.html) \ No newline at end of file +## Title: View Plugin Development + +In most cases, we need to read the data, render the template and then present it to the user. The framework does not force the use of a template engine, allowing developers to select the [template](../core/view.md) themselves. For details, see [Template Rendering](../core/view.md). + +This article describes the framework's specification constraints on the View plugin, and we can use this to encapsulate the corresponding template engine plugin. The following takes [egg-view-ejs] as an example + +## Plugin directory structure + +```bash +egg-view-ejs +├── config +│ ├── config.default.js +│ └── config.local.js +├── lib +│ └── view.js +├── app.js +├── test +├── History.md +├── README.md +└── package.json +``` + +## Plugin naming convention + +* Follow the [plugin development specification](./plugin.md) +* According to the convention, the names of plugins start with `egg-view-` +* `package.json` is configured as follows. Plugins are named after the template engine, such as ejs + +```json +{ + "name": "egg-view-ejs", + "eggPlugin": { + "name": "ejs" + }, + "keywords": ["egg", "egg-plugin", "egg-view", "ejs"] +} +``` + +* The configuration item is also named after the template engine + +```js +// config/config.default.js +module.exports = { + ejs: {} +}; +``` + +## View base class + +The next step is to provide a View base class that will be instantiated on each request. + +The base class of the View needs to provide `render` and `renderString` methods and supports generator and async functions (it can also be a function that returns a Promise). The `render` method is used to render files, and the `renderString` method is used to render template strings. + +The following is a simplified code that can be directly [view source](https://github.com/eggjs/egg-view-ejs/blob/master/lib/view.js) + +```js +const ejs = require('ejs'); + +Mmdule.exports = class EjsView { + render(filename, locals) { + return new Promise((resolve, reject) => { + // Asynchronous API call + ejs.renderFile(filename, locals, (err, result) => { + if (err) { + reject(err); + } else { + resolve(result); + } + }); + }); + } + + renderString(tpl, locals) { + try { + // Synchronous API call + return Promise.resolve(ejs.render(tpl, locals)); + } catch (err) { + return Promise.reject(err); + } + } +}; +``` + +### Parameters + +The three parameters of the `render` method are + +* filename: is the path to the complete file. The framework determines if the file exists when it looks for the file. It does not need to be processed here. +* locals: The data needed for rendering. The data comes from `app.locals`, `ctx.locals` and calls `render` methods. The framework also has built in `ctx`, `request`, `ctx.helper` objects. +* viewOptions: The incoming configuration of the user, which can override the default configuration of the template engine. This can be considered based on the characteristics of the template engine. For example, the cache is enabled by default but a page does not need to be cached. + +The three parameters of the `renderString` method + +* tpl: template string, not file path +* locals: same with `render` +* viewOptions: same with `render` + +## Plugin configuration + +According to the naming conventions mentioned above, the configuration name is generally the name of the template engine, such as ejs + +The configuration of the plugin mainly comes from the configuration of the template engine, and the configuration items can be defined according to the specific conditions, such as the [configuration of ejs](https://github.com/mde/ejs#options) + +```js +// config/config.default.js +module.exports = { + ejs: { + cache: true + } +}; +``` + +### Helper + +The framework provides `ctx.helper` for developer use, but in some cases we want to override the helper method and only take effect when the template is rendered. + +In template rendering, we often need to output a user-supplied html fragment, in which case, we often use the `helper.shtml` provided by the `egg-security` plugin. + +```html +