1 | # Consolidate.js
|
2 |
|
3 | Template engine consolidation library.
|
4 |
|
5 | ## Installation
|
6 |
|
7 | $ npm install consolidate
|
8 |
|
9 | ## Supported template engines
|
10 |
|
11 | - [atpl](https://github.com/soywiz/atpl.js)
|
12 | - [bracket](https://github.com/danlevan/bracket-template)
|
13 | - [doT.js](https://github.com/olado/doT) [(website)](http://olado.github.io/doT/)
|
14 | - [dust (unmaintained)](https://github.com/akdubya/dustjs) [(website)](http://akdubya.github.com/dustjs/)
|
15 | - [dustjs-linkedin (maintained fork of dust)](https://github.com/linkedin/dustjs) [(website)](http://linkedin.github.io/dustjs/)
|
16 | - [eco](https://github.com/sstephenson/eco)
|
17 | - [ect](https://github.com/baryshev/ect) [(website)](http://ectjs.com/)
|
18 | - [ejs](https://github.com/mde/ejs) [(website)](http://ejs.co/)
|
19 | - [haml](https://github.com/visionmedia/haml.js)
|
20 | - [haml-coffee](https://github.com/9elements/haml-coffee)
|
21 | - [hamlet](https://github.com/gregwebs/hamlet.js)
|
22 | - [handlebars](https://github.com/wycats/handlebars.js/) [(website)](http://handlebarsjs.com/)
|
23 | - [hogan](https://github.com/twitter/hogan.js) [(website)](http://twitter.github.com/hogan.js/)
|
24 | - [htmling](https://github.com/codemix/htmling)
|
25 | - [jade](https://github.com/visionmedia/jade) [(website)](http://jade-lang.com/)
|
26 | - [jazz](https://github.com/shinetech/jazz)
|
27 | - [jqtpl](https://github.com/kof/jqtpl)
|
28 | - [JUST](https://github.com/baryshev/just)
|
29 | - [liquor](https://github.com/chjj/liquor)
|
30 | - [lodash](https://github.com/bestiejs/lodash) [(website)](http://lodash.com/)
|
31 | - [marko](https://github.com/marko-js/marko) [(website)](http://markojs.com)
|
32 | - [mote](https://github.com/satchmorun/mote) [(website)](http://satchmorun.github.io/mote/)
|
33 | - [mustache](https://github.com/janl/mustache.js)
|
34 | - [nunjucks](https://github.com/mozilla/nunjucks) [(website)](https://mozilla.github.io/nunjucks)
|
35 | - [plates](https://github.com/flatiron/plates)
|
36 | - [pug (formerly jade)](https://github.com/pugjs/pug) [(website)](http://jade-lang.com/)
|
37 | - [QEJS](https://github.com/jepso/QEJS)
|
38 | - [ractive](https://github.com/Rich-Harris/Ractive)
|
39 | - [react](https://github.com/facebook/react)
|
40 | - [slm](https://github.com/slm-lang/slm)
|
41 | - [swig (unmaintained)](https://github.com/paularmstrong/swig)
|
42 | - [swig (maintained fork)](https://github.com/node-swig/swig-templates)
|
43 | - [teacup](https://github.com/goodeggs/teacup)
|
44 | - [templayed](http://archan937.github.com/templayed.js/)
|
45 | - [twig](https://github.com/justjohn/twig.js)
|
46 | - [liquid](https://github.com/leizongmin/tinyliquid) [(website)](http://liquidmarkup.org/)
|
47 | - [toffee](https://github.com/malgorithms/toffee)
|
48 | - [underscore](https://github.com/documentcloud/underscore) [(website)](http://underscorejs.org/#template)
|
49 | - [vash](https://github.com/kirbysayshi/vash)
|
50 | - [walrus](https://github.com/jeremyruppel/walrus) [(website)](http://documentup.com/jeremyruppel/walrus/)
|
51 | - [whiskers](https://github.com/gsf/whiskers.js)
|
52 |
|
53 | __NOTE__: you must still install the engines you wish to use, add them to your package.json dependencies.
|
54 |
|
55 | ## API
|
56 |
|
57 | All templates supported by this library may be rendered using the signature `(path[, locals], callback)` as shown below, which happens to be the signature that Express 3.x supports so any of these engines may be used within Express.
|
58 |
|
59 | __NOTE__: All this example code uses cons.swig for the swig template engine. Replace swig with whatever templating you are using. For example, use cons.hogan for hogan.js, cons.jade for jade, etc. `console.log(cons)` for the full list of identifiers.
|
60 |
|
61 | ```js
|
62 | var cons = require('consolidate');
|
63 | cons.swig('views/page.html', { user: 'tobi' }, function(err, html){
|
64 | if (err) throw err;
|
65 | console.log(html);
|
66 | });
|
67 | ```
|
68 |
|
69 | Or without options / local variables:
|
70 |
|
71 | ```js
|
72 | var cons = require('consolidate');
|
73 | cons.swig('views/page.html', function(err, html){
|
74 | if (err) throw err;
|
75 | console.log(html);
|
76 | });
|
77 | ```
|
78 |
|
79 | To dynamically pass the engine, simply use the subscript operator and a variable:
|
80 |
|
81 | ```js
|
82 | var cons = require('consolidate')
|
83 | , name = 'swig';
|
84 |
|
85 | cons[name]('views/page.html', { user: 'tobi' }, function(err, html){
|
86 | if (err) throw err;
|
87 | console.log(html);
|
88 | });
|
89 | ```
|
90 |
|
91 | ### Promises
|
92 |
|
93 | Additionally, all templates optionally return a promise if no callback function is provided. The promise represents the eventual result of the template function which will either resolve to a string, compiled from the template, or be rejected. Promises expose a `then` method which registers callbacks to receive the promise’s eventual value and a `catch` method which the reason why the promise could not be fulfilled. Promises allow more synchronous-like code structure and solve issues like race conditions.
|
94 |
|
95 | ```js
|
96 | var cons = require('consolidate');
|
97 |
|
98 | cons.swig('views/page.html', { user: 'tobi' })
|
99 | .then(function (html) {
|
100 | console.log(html);
|
101 | })
|
102 | .catch(function (err) {
|
103 | throw err;
|
104 | });
|
105 | ```
|
106 |
|
107 | ## Caching
|
108 |
|
109 | To enable caching simply pass `{ cache: true }`. Engines _may_ use this option to cache things reading the file contents, compiled `Function`s etc. Engines which do _not_ support this may simply ignore it. All engines that consolidate.js implements I/O for will cache the file contents, ideal for production environments.
|
110 | When using consolidate directly: `cons.swig('views/page.html', { user: 'tobi', cache:true }, callback);`
|
111 | Using Express 3 or higher: `app.locals.cache = true` or set NODE_ENV to 'production' and Express will do this for you.
|
112 |
|
113 | ## Express 3.x example
|
114 |
|
115 | ```js
|
116 | var express = require('express')
|
117 | , cons = require('consolidate')
|
118 | , app = express();
|
119 |
|
120 | // assign the swig engine to .html files
|
121 | app.engine('html', cons.swig);
|
122 |
|
123 | // set .html as the default extension
|
124 | app.set('view engine', 'html');
|
125 | app.set('views', __dirname + '/views');
|
126 |
|
127 | var users = [];
|
128 | users.push({ name: 'tobi' });
|
129 | users.push({ name: 'loki' });
|
130 | users.push({ name: 'jane' });
|
131 |
|
132 | app.get('/', function(req, res){
|
133 | res.render('index', {
|
134 | title: 'Consolidate.js'
|
135 | });
|
136 | });
|
137 |
|
138 | app.get('/users', function(req, res){
|
139 | res.render('users', {
|
140 | title: 'Users',
|
141 | users: users
|
142 | });
|
143 | });
|
144 |
|
145 | app.listen(3000);
|
146 | console.log('Express server listening on port 3000');
|
147 | ```
|
148 |
|
149 | ## Template Engine Instances
|
150 |
|
151 | Template engines are exposed via the `cons.requires` object, but they are not instantiated until you've called the `cons[engine].render()` method. You can instantiate them manually beforehand if you want to add filters, globals, mixins, or other engine features.
|
152 |
|
153 | ```js
|
154 | var cons = require('consolidate'),
|
155 | nunjucks = require('nunjucks');
|
156 |
|
157 | // add nunjucks to requires so filters can be
|
158 | // added and the same instance will be used inside the render method
|
159 | cons.requires.nunjucks = nunjucks.configure();
|
160 |
|
161 | cons.requires.nunjucks.addFilter('foo', function () {
|
162 | return 'bar';
|
163 | });
|
164 | ```
|
165 |
|
166 | ## Notes
|
167 |
|
168 | * If you're using Nunjucks, please take a look at the `exports.nunjucks.render` function in `lib.consolidate.js`. You can pass your own engine/environment via `options.nunjucksEnv`, or if you want to support Express you can pass `options.settings.views`, or if you have another use case, pass `options.nunjucks` (see the code for more insight).
|
169 | * You can pass **partials** with `options.partials`
|
170 | * For using **template inheritance** with nunjucks, you can pass a loader
|
171 | with `options.loader`.
|
172 | * To use **filters** with tinyliquid, use `options.filters` and specify an array of properties, each of which is a named filter function. A filter function takes a string as a parameter and returns a modified version of it.
|
173 | * To use **custom tags** with tinyliquid, use `options.customTags` to specify an array of tag functions that follow the tinyliquid [custom tag](https://github.com/leizongmin/tinyliquid/wiki/Custom-Tag) definition.
|
174 | * The default directory used with the **include** tag with tinyliquid is the current working directory. To override this, use `options.includeDir`.
|
175 | * `React` To render content into a html base template (eg. `index.html` of your React app), pass the path of the template with `options.base`.
|
176 |
|
177 | ## Running tests
|
178 |
|
179 | Install dev deps:
|
180 |
|
181 | $ npm install -d
|
182 |
|
183 | Run the tests:
|
184 |
|
185 | $ make test
|
186 |
|
187 | ## License
|
188 |
|
189 | (The MIT License)
|
190 |
|
191 | Copyright (c) 2011-2016 TJ Holowaychuk <tj@vision-media.ca>
|
192 |
|
193 | Permission is hereby granted, free of charge, to any person obtaining
|
194 | a copy of this software and associated documentation files (the
|
195 | 'Software'), to deal in the Software without restriction, including
|
196 | without limitation the rights to use, copy, modify, merge, publish,
|
197 | distribute, sublicense, and/or sell copies of the Software, and to
|
198 | permit persons to whom the Software is furnished to do so, subject to
|
199 | the following conditions:
|
200 |
|
201 | The above copyright notice and this permission notice shall be
|
202 | included in all copies or substantial portions of the Software.
|
203 |
|
204 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
205 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
206 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
207 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
208 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
209 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
210 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|