1 | # EJS
|
2 |
|
3 | Embedded JavaScript templates
|
4 |
|
5 | [![Build Status](https://img.shields.io/travis/mde/ejs/master.svg?style=flat)](https://travis-ci.org/mde/ejs)
|
6 | [![Developing Dependencies](https://img.shields.io/david/dev/mde/ejs.svg?style=flat)](https://david-dm.org/mde/ejs?type=dev)
|
7 | [![Known Vulnerabilities](https://snyk.io/test/npm/ejs/badge.svg?style=flat)](https://snyk.io/test/npm/ejs)
|
8 |
|
9 | ## Installation
|
10 |
|
11 | ```bash
|
12 | $ npm install ejs
|
13 | ```
|
14 |
|
15 | ## Features
|
16 |
|
17 | * Control flow with `<% %>`
|
18 | * Escaped output with `<%= %>` (escape function configurable)
|
19 | * Unescaped raw output with `<%- %>`
|
20 | * Newline-trim mode ('newline slurping') with `-%>` ending tag
|
21 | * Whitespace-trim mode (slurp all whitespace) for control flow with `<%_ _%>`
|
22 | * Custom delimiters (e.g., use `<? ?>` instead of `<% %>`)
|
23 | * Includes
|
24 | * Client-side support
|
25 | * Static caching of intermediate JavaScript
|
26 | * Static caching of templates
|
27 | * Complies with the [Express](http://expressjs.com) view system
|
28 |
|
29 | ## Example
|
30 |
|
31 | ```ejs
|
32 | <% if (user) { %>
|
33 | <h2><%= user.name %></h2>
|
34 | <% } %>
|
35 | ```
|
36 |
|
37 | Try EJS online at: https://ionicabizau.github.io/ejs-playground/.
|
38 |
|
39 | ## Usage
|
40 |
|
41 | ```javascript
|
42 | let template = ejs.compile(str, options);
|
43 | template(data);
|
44 | // => Rendered HTML string
|
45 |
|
46 | ejs.render(str, data, options);
|
47 | // => Rendered HTML string
|
48 |
|
49 | ejs.renderFile(filename, data, options, function(err, str){
|
50 | // str => Rendered HTML string
|
51 | });
|
52 | ```
|
53 |
|
54 | It is also possible to use `ejs.render(dataAndOptions);` where you pass
|
55 | everything in a single object. In that case, you'll end up with local variables
|
56 | for all the passed options. However, be aware that your code could break if we
|
57 | add an option with the same name as one of your data object's properties.
|
58 | Therefore, we do not recommend using this shortcut.
|
59 |
|
60 | ## Options
|
61 |
|
62 | - `cache` Compiled functions are cached, requires `filename`
|
63 | - `filename` The name of the file being rendered. Not required if you
|
64 | are using `renderFile()`. Used by `cache` to key caches, and for includes.
|
65 | - `root` Set project root for includes with an absolute path (/file.ejs).
|
66 | - `context` Function execution context
|
67 | - `compileDebug` When `false` no debug instrumentation is compiled
|
68 | - `client` When `true`, compiles a function that can be rendered
|
69 | in the browser without needing to load the EJS Runtime
|
70 | ([ejs.min.js](https://github.com/mde/ejs/releases/latest)).
|
71 | - `delimiter` Character to use with angle brackets for open/close
|
72 | - `debug` Output generated function body
|
73 | - `strict` When set to `true`, generated function is in strict mode
|
74 | - `_with` Whether or not to use `with() {}` constructs. If `false`
|
75 | then the locals will be stored in the `locals` object. Set to `false` in strict mode.
|
76 | - `destructuredLocals` An array of local variables that are always destructured from
|
77 | the locals object, available even in strict mode.
|
78 | - `localsName` Name to use for the object storing local variables when not using
|
79 | `with` Defaults to `locals`
|
80 | - `rmWhitespace` Remove all safe-to-remove whitespace, including leading
|
81 | and trailing whitespace. It also enables a safer version of `-%>` line
|
82 | slurping for all scriptlet tags (it does not strip new lines of tags in
|
83 | the middle of a line).
|
84 | - `escape` The escaping function used with `<%=` construct. It is
|
85 | used in rendering and is `.toString()`ed in the generation of client functions.
|
86 | (By default escapes XML).
|
87 | - `outputFunctionName` Set to a string (e.g., 'echo' or 'print') for a function to print
|
88 | output inside scriptlet tags.
|
89 | - `async` When `true`, EJS will use an async function for rendering. (Depends
|
90 | on async/await support in the JS runtime.
|
91 |
|
92 | This project uses [JSDoc](http://usejsdoc.org/). For the full public API
|
93 | documentation, clone the repository and run `npm run doc`. This will run JSDoc
|
94 | with the proper options and output the documentation to `out/`. If you want
|
95 | the both the public & private API docs, run `npm run devdoc` instead.
|
96 |
|
97 | ## Tags
|
98 |
|
99 | - `<%` 'Scriptlet' tag, for control-flow, no output
|
100 | - `<%_` 'Whitespace Slurping' Scriptlet tag, strips all whitespace before it
|
101 | - `<%=` Outputs the value into the template (escaped)
|
102 | - `<%-` Outputs the unescaped value into the template
|
103 | - `<%#` Comment tag, no execution, no output
|
104 | - `<%%` Outputs a literal '<%'
|
105 | - `%%>` Outputs a literal '%>'
|
106 | - `%>` Plain ending tag
|
107 | - `-%>` Trim-mode ('newline slurp') tag, trims following newline
|
108 | - `_%>` 'Whitespace Slurping' ending tag, removes all whitespace after it
|
109 |
|
110 | For the full syntax documentation, please see [docs/syntax.md](https://github.com/mde/ejs/blob/master/docs/syntax.md).
|
111 |
|
112 | ## Includes
|
113 |
|
114 | Includes either have to be an absolute path, or, if not, are assumed as
|
115 | relative to the template with the `include` call. For example if you are
|
116 | including `./views/user/show.ejs` from `./views/users.ejs` you would
|
117 | use `<%- include('user/show') %>`.
|
118 |
|
119 | You must specify the `filename` option for the template with the `include`
|
120 | call unless you are using `renderFile()`.
|
121 |
|
122 | You'll likely want to use the raw output tag (`<%-`) with your include to avoid
|
123 | double-escaping the HTML output.
|
124 |
|
125 | ```ejs
|
126 | <ul>
|
127 | <% users.forEach(function(user){ %>
|
128 | <%- include('user/show', {user: user}) %>
|
129 | <% }); %>
|
130 | </ul>
|
131 | ```
|
132 |
|
133 | Includes are inserted at runtime, so you can use variables for the path in the
|
134 | `include` call (for example `<%- include(somePath) %>`). Variables in your
|
135 | top-level data object are available to all your includes, but local variables
|
136 | need to be passed down.
|
137 |
|
138 | NOTE: Include preprocessor directives (`<% include user/show %>`) are
|
139 | still supported.
|
140 |
|
141 | ## Custom delimiters
|
142 |
|
143 | Custom delimiters can be applied on a per-template basis, or globally:
|
144 |
|
145 | ```javascript
|
146 | let ejs = require('ejs'),
|
147 | users = ['geddy', 'neil', 'alex'];
|
148 |
|
149 | // Just one template
|
150 | ejs.render('<?= users.join(" | "); ?>', {users: users}, {delimiter: '?'});
|
151 | // => 'geddy | neil | alex'
|
152 |
|
153 | // Or globally
|
154 | ejs.delimiter = '$';
|
155 | ejs.render('<$= users.join(" | "); $>', {users: users});
|
156 | // => 'geddy | neil | alex'
|
157 | ```
|
158 |
|
159 | ## Caching
|
160 |
|
161 | EJS ships with a basic in-process cache for caching the intermediate JavaScript
|
162 | functions used to render templates. It's easy to plug in LRU caching using
|
163 | Node's `lru-cache` library:
|
164 |
|
165 | ```javascript
|
166 | let ejs = require('ejs'),
|
167 | LRU = require('lru-cache');
|
168 | ejs.cache = LRU(100); // LRU cache with 100-item limit
|
169 | ```
|
170 |
|
171 | If you want to clear the EJS cache, call `ejs.clearCache`. If you're using the
|
172 | LRU cache and need a different limit, simple reset `ejs.cache` to a new instance
|
173 | of the LRU.
|
174 |
|
175 | ## Custom file loader
|
176 |
|
177 | The default file loader is `fs.readFileSync`, if you want to customize it, you can set ejs.fileLoader.
|
178 |
|
179 | ```javascript
|
180 | let ejs = require('ejs');
|
181 | let myFileLoad = function (filePath) {
|
182 | return 'myFileLoad: ' + fs.readFileSync(filePath);
|
183 | };
|
184 |
|
185 | ejs.fileLoader = myFileLoad;
|
186 | ```
|
187 |
|
188 | With this feature, you can preprocess the template before reading it.
|
189 |
|
190 | ## Layouts
|
191 |
|
192 | EJS does not specifically support blocks, but layouts can be implemented by
|
193 | including headers and footers, like so:
|
194 |
|
195 |
|
196 | ```ejs
|
197 | <%- include('header') -%>
|
198 | <h1>
|
199 | Title
|
200 | </h1>
|
201 | <p>
|
202 | My page
|
203 | </p>
|
204 | <%- include('footer') -%>
|
205 | ```
|
206 |
|
207 | ## Client-side support
|
208 |
|
209 | Go to the [Latest Release](https://github.com/mde/ejs/releases/latest), download
|
210 | `./ejs.js` or `./ejs.min.js`. Alternately, you can compile it yourself by cloning
|
211 | the repository and running `jake build` (or `$(npm bin)/jake build` if jake is
|
212 | not installed globally).
|
213 |
|
214 | Include one of these files on your page, and `ejs` should be available globally.
|
215 |
|
216 | ### Example
|
217 |
|
218 | ```html
|
219 | <div id="output"></div>
|
220 | <script src="ejs.min.js"></script>
|
221 | <script>
|
222 | let people = ['geddy', 'neil', 'alex'],
|
223 | html = ejs.render('<%= people.join(", "); %>', {people: people});
|
224 | // With jQuery:
|
225 | $('#output').html(html);
|
226 | // Vanilla JS:
|
227 | document.getElementById('output').innerHTML = html;
|
228 | </script>
|
229 | ```
|
230 |
|
231 | ### Caveats
|
232 |
|
233 | Most of EJS will work as expected; however, there are a few things to note:
|
234 |
|
235 | 1. Obviously, since you do not have access to the filesystem, `ejs.renderFile()` won't work.
|
236 | 2. For the same reason, `include`s do not work unless you use an `include callback`. Here is an example:
|
237 | ```javascript
|
238 | let str = "Hello <%= include('file', {person: 'John'}); %>",
|
239 | fn = ejs.compile(str, {client: true});
|
240 |
|
241 | fn(data, null, function(path, d){ // include callback
|
242 | // path -> 'file'
|
243 | // d -> {person: 'John'}
|
244 | // Put your code here
|
245 | // Return the contents of file as a string
|
246 | }); // returns rendered string
|
247 | ```
|
248 |
|
249 | See the [examples folder](https://github.com/mde/ejs/tree/master/examples) for more details.
|
250 |
|
251 | ### IDE Integration with Syntax Highlighting
|
252 |
|
253 | VSCode:Javascript EJS by *DigitalBrainstem*
|
254 |
|
255 | ## Related projects
|
256 |
|
257 | There are a number of implementations of EJS:
|
258 |
|
259 | * TJ's implementation, the v1 of this library: https://github.com/tj/ejs
|
260 | * Jupiter Consulting's EJS: http://www.embeddedjs.com/
|
261 | * EJS Embedded JavaScript Framework on Google Code: https://code.google.com/p/embeddedjavascript/
|
262 | * Sam Stephenson's Ruby implementation: https://rubygems.org/gems/ejs
|
263 | * Erubis, an ERB implementation which also runs JavaScript: http://www.kuwata-lab.com/erubis/users-guide.04.html#lang-javascript
|
264 | * DigitalBrainstem EJS Language support: https://github.com/Digitalbrainstem/ejs-grammar
|
265 |
|
266 | ## License
|
267 |
|
268 | Licensed under the Apache License, Version 2.0
|
269 | (<http://www.apache.org/licenses/LICENSE-2.0>)
|
270 |
|
271 | - - -
|
272 | EJS Embedded JavaScript templates copyright 2112
|
273 | mde@fleegix.org.
|
274 |
|
\ | No newline at end of file |