1 | # koa-views
|
2 |
|
3 | [![Build status][travis-image]][travis-url]
|
4 | [![NPM version][npm-image]][npm-url]
|
5 | [![NPM downloads][npm-downloads-image]][npm-url]
|
6 | [![Dependency Status][david-image]][david-url]
|
7 | [![License][license-image]][license-url]
|
8 |
|
9 | Template rendering middleware for koa.
|
10 |
|
11 | > **Note:** This master branch is for `koa@2`. Take a look at the `v1.x` branch for `koa@1` (not supported).
|
12 |
|
13 | ## Installation
|
14 |
|
15 | ```sh
|
16 | npm install koa-views
|
17 | ```
|
18 |
|
19 | ## Templating engines
|
20 |
|
21 | `koa-views` is using [consolidate](https://github.com/tj/consolidate.js) under the hood.
|
22 |
|
23 | [List of supported engines](https://github.com/tj/consolidate.js#supported-template-engines)
|
24 |
|
25 | ## Example
|
26 |
|
27 | ```js
|
28 | var views = require('koa-views');
|
29 |
|
30 | // Must be used before any router is used
|
31 | app.use(views(__dirname + '/views', {
|
32 | map: {
|
33 | html: 'underscore'
|
34 | }
|
35 | }));
|
36 |
|
37 | app.use(async function (ctx, next) {
|
38 | ctx.state = {
|
39 | session: this.session,
|
40 | title: 'app'
|
41 | };
|
42 |
|
43 | await ctx.render('user', {
|
44 | user: 'John'
|
45 | });
|
46 | });
|
47 | ```
|
48 |
|
49 | For more examples you can take a look at the [tests](./test/index.js).
|
50 |
|
51 | ## Simple middleware
|
52 |
|
53 | If you need to simply render pages with locals, you can install `koa-views-render`:
|
54 |
|
55 | ```sh
|
56 | npm install koa-views-render
|
57 | ```
|
58 |
|
59 | Then simply use it on your routes and its arguments will be passed to `ctx.render`.
|
60 |
|
61 | ```js
|
62 | var render = require('koa-views-render');
|
63 |
|
64 | // ...
|
65 |
|
66 | app.use(render('home', { title 'Home Page' });
|
67 | ```
|
68 |
|
69 | ## API
|
70 |
|
71 | #### `views(root, opts)`
|
72 |
|
73 | * `root`: Where your views are located. Must be an absolute path. All rendered views are relative to this path
|
74 | * `opts` (optional)
|
75 | * `opts.extension`: Default extension for your views
|
76 |
|
77 | Instead of providing the full file extension you can omit it.
|
78 | ```js
|
79 | app.use(async function (ctx) {
|
80 | await ctx.render('user.pug')
|
81 | })
|
82 | ```
|
83 |
|
84 | vs.
|
85 |
|
86 | ```js
|
87 | app.use(views(__dirname, { extension: 'pug' }))
|
88 |
|
89 | app.use(async function (ctx) {
|
90 | await ctx.render('user')
|
91 | })
|
92 | ```
|
93 |
|
94 | * `opts.map`: Map a file extension to an engine
|
95 |
|
96 | In this example, each file ending with `.html` will get rendered using the `nunjucks` templating engine.
|
97 | ```js
|
98 | app.use(views(__dirname, { map: {html: 'nunjucks' }}))
|
99 |
|
100 | // render `user.html` with nunjucks
|
101 | app.use(async function (ctx) {
|
102 | await ctx.render('user.html')
|
103 | })
|
104 | ```
|
105 |
|
106 | * `opts.engineSource`: replace consolidate as default engine source
|
107 |
|
108 | If you’re not happy with consolidate or want more control over the engines, you can override it with this options. `engineSource` should
|
109 | be an object that maps an extension to a function that receives a path and options and returns a promise. In this example templates with the `foo` extension will always return `bar`.
|
110 |
|
111 | ```js
|
112 | app.use(views(__dirname, { engineSource: {foo: () => Promise.resolve('bar')}}))
|
113 |
|
114 | app.use(async function (ctx) {
|
115 | await ctx.render('index.foo')
|
116 | })
|
117 | ```
|
118 |
|
119 | * `opts.options`: These options will get passed to the view engine. This is the time to add `partials` and `helpers` etc.
|
120 |
|
121 | ```js
|
122 | const app = new Koa()
|
123 | .use(views(__dirname, {
|
124 | map: { hbs: 'handlebars' },
|
125 | options: {
|
126 | helpers: {
|
127 | uppercase: (str) => str.toUpperCase()
|
128 | },
|
129 |
|
130 | partials: {
|
131 | subTitle: './my-partial' // requires ./my-partial.hbs
|
132 | }
|
133 | }
|
134 | }))
|
135 | .use(function (ctx) {
|
136 | ctx.state = { title: 'my title', author: 'queckezz' }
|
137 | return ctx.render('./my-view.hbs')
|
138 | })
|
139 | ```
|
140 |
|
141 | ## Debug
|
142 |
|
143 | Set the `DEBUG` environment variable to `koa-views` when starting your server.
|
144 |
|
145 | ```bash
|
146 | $ DEBUG=koa-views
|
147 | ```
|
148 |
|
149 | ## License
|
150 |
|
151 | [MIT](./license)
|
152 |
|
153 | [travis-image]: https://img.shields.io/travis/queckezz/koa-views.svg?style=flat-square
|
154 | [travis-url]: https://travis-ci.org/queckezz/koa-views
|
155 | [npm-image]: https://img.shields.io/npm/v/koa-views.svg?style=flat-square
|
156 | [npm-downloads-image]: https://img.shields.io/npm/dm/koa-views.svg?style=flat-square
|
157 | [npm-url]: https://npmjs.org/package/koa-views
|
158 | [david-image]: http://img.shields.io/david/queckezz/koa-views.svg?style=flat-square
|
159 | [david-url]: https://david-dm.org/queckezz/koa-views
|
160 | [license-image]: http://img.shields.io/npm/l/koa-views.svg?style=flat-square
|
161 | [license-url]: ./license
|