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 | - [doT.js](https://github.com/olado/doT) [(website)](http://olado.github.io/doT/)
|
13 | - [dust (unmaintained)](https://github.com/akdubya/dustjs) [(website)](http://akdubya.github.com/dustjs/)
|
14 | - [dustjs-linkedin (maintained fork of dust)](https://github.com/linkedin/dustjs) [(website)](http://linkedin.github.io/dustjs/)
|
15 | - [eco](https://github.com/sstephenson/eco)
|
16 | - [ect](https://github.com/baryshev/ect) [(website)](http://ectjs.com/)
|
17 | - [ejs](https://github.com/visionmedia/ejs)
|
18 | - [haml](https://github.com/visionmedia/haml.js)
|
19 | - [haml-coffee](https://github.com/9elements/haml-coffee)
|
20 | - [hamlet](https://github.com/gregwebs/hamlet.js)
|
21 | - [handlebars](https://github.com/wycats/handlebars.js/) [(website)](http://handlebarsjs.com/)
|
22 | - [hogan](https://github.com/twitter/hogan.js) [(website)](http://twitter.github.com/hogan.js/)
|
23 | - [htmling](https://github.com/codemix/htmling)
|
24 | - [jade](https://github.com/visionmedia/jade) [(website)](http://jade-lang.com/)
|
25 | - [jazz](https://github.com/shinetech/jazz)
|
26 | - [jqtpl](https://github.com/kof/jqtpl)
|
27 | - [JUST](https://github.com/baryshev/just)
|
28 | - [liquor](https://github.com/chjj/liquor)
|
29 | - [lodash](https://github.com/bestiejs/lodash) [(website)](http://lodash.com/)
|
30 | - [mote](https://github.com/satchmorun/mote) [(website)](http://satchmorun.github.io/mote/)
|
31 | - [mustache](https://github.com/janl/mustache.js)
|
32 | - [nunjucks](https://github.com/mozilla/nunjucks) [(website)](https://mozilla.github.io/nunjucks)
|
33 | - [pug (formerly jade)](https://github.com/pugjs/jade) [(website)](http://jade-lang.com/)
|
34 | - [QEJS](https://github.com/jepso/QEJS)
|
35 | - [ractive](https://github.com/Rich-Harris/Ractive)
|
36 | - [react](https://github.com/facebook/react)
|
37 | - [slm](https://github.com/slm-lang/slm)
|
38 | - [swig](https://github.com/paularmstrong/swig) [(website)](http://paularmstrong.github.com/swig/)
|
39 | - [templayed](http://archan937.github.com/templayed.js/)
|
40 | - [twig](https://github.com/justjohn/twig.js)
|
41 | - [liquid](https://github.com/leizongmin/tinyliquid) [(website)](http://liquidmarkup.org/)
|
42 | - [toffee](https://github.com/malgorithms/toffee)
|
43 | - [underscore](https://github.com/documentcloud/underscore) [(website)](http://underscorejs.org/#template)
|
44 | - [vash](https://github.com/kirbysayshi/vash)
|
45 | - [walrus](https://github.com/jeremyruppel/walrus) [(website)](http://documentup.com/jeremyruppel/walrus/)
|
46 | - [whiskers](https://github.com/gsf/whiskers.js)
|
47 |
|
48 | __NOTE__: you must still install the engines you wish to use, add them to your package.json dependencies.
|
49 |
|
50 | ## API
|
51 |
|
52 | 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.
|
53 |
|
54 | __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.
|
55 |
|
56 | ```js
|
57 | var cons = require('consolidate');
|
58 | cons.swig('views/page.html', { user: 'tobi' }, function(err, html){
|
59 | if (err) throw err;
|
60 | console.log(html);
|
61 | });
|
62 | ```
|
63 |
|
64 | Or without options / local variables:
|
65 |
|
66 | ```js
|
67 | var cons = require('consolidate');
|
68 | cons.swig('views/page.html', function(err, html){
|
69 | if (err) throw err;
|
70 | console.log(html);
|
71 | });
|
72 | ```
|
73 |
|
74 | To dynamically pass the engine, simply use the subscript operator and a variable:
|
75 |
|
76 | ```js
|
77 | var cons = require('consolidate')
|
78 | , name = 'swig';
|
79 |
|
80 | cons[name]('views/page.html', { user: 'tobi' }, function(err, html){
|
81 | if (err) throw err;
|
82 | console.log(html);
|
83 | });
|
84 | ```
|
85 |
|
86 | ### Promises
|
87 |
|
88 | 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.
|
89 |
|
90 | ```js
|
91 | var cons = require('consolidate');
|
92 |
|
93 | cons.swig('views/page.html', { user: 'tobi' })
|
94 | .then(function (html) {
|
95 | console.log(html);
|
96 | })
|
97 | .catch(function (err) {
|
98 | throw err;
|
99 | });
|
100 | ```
|
101 |
|
102 | ## Caching
|
103 |
|
104 | To enable or disable caching simply pass `{ cache: true/false }`. 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.
|
105 |
|
106 | ```js
|
107 | var cons = require('consolidate');
|
108 | cons.swig('views/page.html', { cache: false, user: 'tobi' }, function(err, html){
|
109 | if (err) throw err;
|
110 | console.log(html);
|
111 | });
|
112 | ```
|
113 |
|
114 | ## Express 3.x example
|
115 |
|
116 | ```js
|
117 | var express = require('express')
|
118 | , cons = require('consolidate')
|
119 | , app = express();
|
120 |
|
121 | // assign the swig engine to .html files
|
122 | app.engine('html', cons.swig);
|
123 |
|
124 | // set .html as the default extension
|
125 | app.set('view engine', 'html');
|
126 | app.set('views', __dirname + '/views');
|
127 |
|
128 | var users = [];
|
129 | users.push({ name: 'tobi' });
|
130 | users.push({ name: 'loki' });
|
131 | users.push({ name: 'jane' });
|
132 |
|
133 | app.get('/', function(req, res){
|
134 | res.render('index', {
|
135 | title: 'Consolidate.js'
|
136 | });
|
137 | });
|
138 |
|
139 | app.get('/users', function(req, res){
|
140 | res.render('users', {
|
141 | title: 'Users',
|
142 | users: users
|
143 | });
|
144 | });
|
145 |
|
146 | app.listen(3000);
|
147 | console.log('Express server listening on port 3000');
|
148 | ```
|
149 |
|
150 | ## Template Engine Instances
|
151 |
|
152 | 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.
|
153 |
|
154 | ```js
|
155 | var cons = require('consolidate'),
|
156 | nunjucks = require('nunjucks');
|
157 |
|
158 | // add nunjucks to requires so filters can be
|
159 | // added and the same instance will be used inside the render method
|
160 | cons.requires.nunjucks = nunjucks.configure();
|
161 |
|
162 | cons.requires.nunjucks.addFilter('foo', function () {
|
163 | return 'bar';
|
164 | });
|
165 | ```
|
166 |
|
167 | ## Notes
|
168 |
|
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.
|