README.md

egg-views

Egg view plugin which is similar to koa-views, supports many templating engines.

Install

egg-views is using consolidate under the hood.

NOTE: you must still install the engine you wish to use, add it to your package.json dependencies.

$ npm i egg-views --save

# Add one of the following:
$ npm i ejs --save
$ npm i vash --save
...

List of supported engines

Usage

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

// if you choose ejs and use .ejs for extension
// {app_root}/config/config.default.js
exports.view = {
  defaultViewEngine: 'views',
  mapping: {
    '.ejs': 'views',
  },
};

// if you choose vash and use .vash for extension
// {app_root}/config/config.default.js
exports.view = {
  defaultViewEngine: 'views',
  mapping: {
    '.vash': 'views',
  },
};

// if you choose vash and use both .html and .vash for extension
// {app_root}/config/config.default.js
exports.view = {
  defaultViewEngine: 'views',
  mapping: {
    '.html': 'views',
    '.vash': 'views',
  },
};

Configuration

Write configurations of the engine you choose to the options.

WARNING: be aware that your code could break if we add an option with the same name as one of your data object's properties. See Conflict.

If you choose to use ejs:

// {app_root}/config/config.default.js
exports.views = {
  engine: 'ejs',
  // ejs config
  options: {
    cache: true,
    debug: false,
    compileDebug: true,
    delimiter: null,
    strict: false,
  },
};

Or choose to use vash:

// {app_root}/config/config.default.js
exports.views = {
  engine: 'vash',
  // vash config
  options: {
    useWith: true,
  },
};

see config/config.default.js for more detail.

Render

There are three default render functions in egg, while the last one is not supported in egg-views.

• ✔︎ render(name, locals) renders template file, and set the value to ctx.body.

• ✔︎ renderView(name, locals) renders template file, returns the result and don't set the value to any variable.

• ✘ renderString(tpl, locals) not supported.

Conflict

Unfortunately, due to the using of egg and consolidate, some occupied names can't be used as your data object's properties:

• ctx
• gettext
• helper
• request
• locals
• name
• root

You should also avoid using the names in configuration options list of the choosing templating engine. Because, if you use these names as your data object's properties, your data will be used as options to build a template firstly, then as the data to construct the final page. For example, if you choose ejs, you should be cautious to use cache filename scope debug ....

Questions & Suggestions

Please open an issue here.

License

MIT