# egg-view

> Base view plugin for egg

Latest version **2.1.4** (published 2023-02-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install egg-view
pnpm add egg-view
yarn add egg-view
bun add egg-view
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.4 |
| Published | 2023-02-03 |
| First published | 2017-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 1 |
| Unpacked size | 22.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 41 |
| Author | popomore |
| Maintainers | dead-horse, atian25, fengmk2, popomore |
| Keywords | egg, eggPlugin, egg-plugin, egg-view, view |

## Links

- npm: https://www.npmjs.com/package/egg-view
- Repository: https://github.com/eggjs/egg-view
- Homepage: https://github.com/eggjs/egg-view#readme
- Issues: https://github.com/eggjs/egg/issues
- npm.io page: https://npm.io/package/egg-view

## Dependencies (1)

- [mz](https://npm.io/package/mz.md) ^2.7.0

## Recent versions

- 2.1.4 (latest) — 2023-02-03
- 1.2.0 (release-1.x) — 2018-03-14
- 2.1.3 — 2020-11-05
- 2.1.2 — 2019-01-30
- 2.1.1 — 2018-12-29
- 2.1.0 — 2018-02-26
- 2.0.0 — 2017-11-13
- 1.1.2 — 2017-07-14
- 1.1.1 — 2017-06-04
- 1.1.0 — 2017-04-01
- 1.0.1 — 2017-02-28
- 1.0.0 — 2017-02-20

## README

# egg-view

[![NPM version](https://img.shields.io/npm/v/egg-view.svg?style=flat-square)](https://npmjs.org/package/egg-view)
[![NPM quality](http://npm.packagequality.com/shield/egg-view.svg?style=flat-square)](http://packagequality.com/#?package=egg-view)
[![NPM download](https://img.shields.io/npm/dm/egg-view.svg?style=flat-square)](https://npmjs.org/package/egg-view)

[![Continuous Integration](https://github.com/egg/egg-view/actions/workflows/nodejs.yml/badge.svg)](https://github.com/egg/egg-view/actions/workflows/nodejs.yml)
[![Test coverage](https://img.shields.io/codecov/c/github/egg/egg-view.svg?style=flat-square)](https://codecov.io/gh/egg/egg-view)


Base view plugin for egg

**it's a plugin that has been built-in for egg.**

## Install

```bash
$ npm i egg-view --save
```

## Usage

```js
// {app_root}/config/plugin.js
exports.view = {
  enable: true,
  package: 'egg-view',
};
```

## Use a template engine

[egg-view] don't have build-in view engine, So you should choose a template engine like [ejs], and install [egg-view-ejs] plugin.

You can choose a template engine first, link [ejs], so we use [egg-view-ejs] plugin.

`egg-view` is in [eggjs], so you just need configure [egg-view-ejs].

```js
// config/plugin.js
exports.ejs = {
  enable: true,
  package: 'egg-view-ejs',
};
```

Configure the mapping, the file with `.ejs` extension will be rendered by ejs.

```js
// config/config.default.js
exports.view = {
  mapping: {
    '.ejs': 'ejs',
  },
};
```

In controller, you can call `ctx.render`.

```js
module.exports = app => {
  return class UserController extends app.Controller {
    async list() {
      const { ctx } = this;
      await ctx.render('user.ejs');
    }
  };
};
```

If you call `ctx.renderString`, you should specify viewEngine in viewOptions.

```js
module.exports = app => {
  return class UserController extends app.Controller {
    async list() {
      const { ctx } = this;
      ctx.body = await ctx.renderString('<%= user %>', { user: 'popomore' }, {
        viewEngine: 'ejs',
      });
    }
  };
};
```

## Use multiple view engine

[egg-view] support multiple view engine, so you can use more than one template engine in one application.

If you want add another template engine like [nunjucks], then you can add [egg-view-nunjucks] plugin.

Configure the plugin and mapping

```js
// config/config.default.js
exports.view = {
  mapping: {
    '.ejs': 'ejs',
    '.nj': 'nunjucks',
  },
};
```

You can simply render the file with `.nj` extension.

```js
await ctx.render('user.nj');
```

## How to write a view plugin

You can use [egg-view]' API to register a plugin.

### View engine

Create a view engine class first, and implement `render` and `renderString`, if the template engine don't support, just throw an error. The view engine is context level, so it receive ctx in `constructor`.

```js
// lib/view.js
module.exports = class MyView {
  constructor(ctx) {
    // do some initialize
    // get the plugin config from `ctx.app.config`
  }

  async render(fullpath, locals) {
    return myengine.render(fullpath, locals);
  }

  async renderString() { throw new Error('not implement'); }
};
```

`render` and `renderString` support generator function, async function, or normal function return a promise.

If the template engine only support callback, you can wrap it by Promise.

```js
class MyView {
  render(fullpath, locals) {
    return new Promise((resolve, reject) => {
      myengine.render(fullpath, locals, (err, result) => {
        if (err) {
          reject(err);
        } else {
          resolve(result);
        }
      });
    });
  }
};
```

These methods receive three arguments, `renderString` will pass tpl as the first argument instead of name in `render`.

`render(name, locals, viewOptions)`

- name: the file path that can resolve from root (`app/view` by default)
- locals: data used by template
- viewOptions: the view options for each render, it can override the view default config in `config/config.default.js`. Plugin should implement it if it has config.
  When you implement view engine, you will receive this options from `render`, the options contain:
  - root: egg-view will resolve the name to full path, but seperating root and name in viewOptions.
  - name: the original name when call render
  - locals: the original locals when call render

`renderString(tpl, locals, viewOptions)`

- tpl: the template string instead of the file, using in `renderString`
- locals: same as `render`
- viewOptions: same as `render`

### Register

After define a view engine, you can register it.

```js
// app.js
module.exports = app => {
  app.view.use('myName', require('./lib/view'));
};
```

You can define a view engine name, normally it's a template name.

### Configure

Define plugin name and depend on [egg-view]

```json
{
  "eggPlugin": {
    "name": "myName",
    "dependencies": [ "view" ]
  }
}
```

Set default config in `config/config.default.js`, the name is equals to plugin name.

```js
exports.myName = {},
```

See some examples

- [egg-view-ejs]
- [egg-view-nunjucks]

## Configuration

### Root

Root is `${baseDir}/app/view` by default, but you can define multiple directory, seperated by `,`. [egg-view] will find a file from all root directories.

```js
module.exports = appInfo => {
  const baseDir = appInfo.baseDir;
  return {
    view: {
      root: `${baseDir}/app/view,${baseDir}/app/view2`
    }
  }
}
```

### defaultExtension

When render a file, you should specify a extension that let [egg-view] know whitch engine you want to use. However you can define `defaultExtension` without write the extension.

```js
// config/config.default.js
exports.view = {
  defaultExtension: '.html',
};

// controller
module.exports = app => {
  return class UserController extends app.Controller {
    async list() {
      const { ctx } = this;
      // render user.html
      await ctx.render('user');
    }
  };
};
```

### viewEngine and defaultViewEngine

If you are using `renderString`, you should specify viewEngine in view config, see example above.

However, you can define `defaultViewEngine` without set each time.

```js
// config/config.default.js
exports.view = {
  defaultViewEngine: 'ejs',
};
```

see [config/config.default.js](https://github.com/eggjs/egg-view/blob/master/config/config.default.js) for more detail.

## Questions & Suggestions

Please open an issue [here](https://github.com/eggjs/egg/issues).

## License

[MIT](https://github.com/eggjs/egg-view/blob/master/LICENSE)


[eggjs]: https://eggjs.org
[ejs]: https://github.com/mde/ejs
[egg-view-ejs]: https://github.com/eggjs/egg-view-ejs
[egg-view]: https://github.com/eggjs/egg-view
[nunjucks]: http://mozilla.github.io/nunjucks
[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

---
_Source: https://npm.io/package/egg-view · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._