3 Embedded JavaScript templates
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-square)](https://snyk.io/test/npm/ejs)
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 `<% %>`)
25 * Static caching of intermediate JavaScript
26 * Static caching of templates
27 * Complies with the [Express](http://expressjs.com) view system
33 <h2><%= user.name %></h2>
37 Try EJS online at: https://ionicabizau.github.io/ejs-playground/.
42 let template = ejs.compile(str, options);
44 // => Rendered HTML string
46 ejs.render(str, data, options);
47 // => Rendered HTML string
49 ejs.renderFile(filename, data, options, function(err, str){
50 // str => Rendered HTML string
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.
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 - `localsName` Name to use for the object storing local variables when not using
77 `with` Defaults to `locals`
78 - `rmWhitespace` Remove all safe-to-remove whitespace, including leading
79 and trailing whitespace. It also enables a safer version of `-%>` line
80 slurping for all scriptlet tags (it does not strip new lines of tags in
81 the middle of a line).
82 - `escape` The escaping function used with `<%=` construct. It is
83 used in rendering and is `.toString()`ed in the generation of client functions.
84 (By default escapes XML).
85 - `outputFunctionName` Set to a string (e.g., 'echo' or 'print') for a function to print
86 output inside scriptlet tags.
87 - `async` When `true`, EJS will use an async function for rendering. (Depends
88 on async/await support in the JS runtime.
90 This project uses [JSDoc](http://usejsdoc.org/). For the full public API
91 documentation, clone the repository and run `npm run doc`. This will run JSDoc
92 with the proper options and output the documentation to `out/`. If you want
93 the both the public & private API docs, run `npm run devdoc` instead.
97 - `<%` 'Scriptlet' tag, for control-flow, no output
98 - `<%_` 'Whitespace Slurping' Scriptlet tag, strips all whitespace before it
99 - `<%=` Outputs the value into the template (escaped)
100 - `<%-` Outputs the unescaped value into the template
101 - `<%#` Comment tag, no execution, no output
102 - `<%%` Outputs a literal '<%'
103 - `%%>` Outputs a literal '%>'
104 - `%>` Plain ending tag
105 - `-%>` Trim-mode ('newline slurp') tag, trims following newline
106 - `_%>` 'Whitespace Slurping' ending tag, removes all whitespace after it
108 For the full syntax documentation, please see [docs/syntax.md](https://github.com/mde/ejs/blob/master/docs/syntax.md).
112 Includes either have to be an absolute path, or, if not, are assumed as
113 relative to the template with the `include` call. For example if you are
114 including `./views/user/show.ejs` from `./views/users.ejs` you would
115 use `<%- include('user/show') %>`.
117 You must specify the `filename` option for the template with the `include`
118 call unless you are using `renderFile()`.
120 You'll likely want to use the raw output tag (`<%-`) with your include to avoid
121 double-escaping the HTML output.
125 <% users.forEach(function(user){ %>
126 <%- include('user/show', {user: user}) %>
131 Includes are inserted at runtime, so you can use variables for the path in the
132 `include` call (for example `<%- include(somePath) %>`). Variables in your
133 top-level data object are available to all your includes, but local variables
134 need to be passed down.
136 NOTE: Include preprocessor directives (`<% include user/show %>`) are
141 Custom delimiters can be applied on a per-template basis, or globally:
144 let ejs = require('ejs'),
145 users = ['geddy', 'neil', 'alex'];
148 ejs.render('<?= users.join(" | "); ?>', {users: users}, {delimiter: '?'});
149 // => 'geddy | neil | alex'
153 ejs.render('<$= users.join(" | "); $>', {users: users});
154 // => 'geddy | neil | alex'
159 EJS ships with a basic in-process cache for caching the intermediate JavaScript
160 functions used to render templates. It's easy to plug in LRU caching using
161 Node's `lru-cache` library:
164 let ejs = require('ejs'),
165 LRU = require('lru-cache');
166 ejs.cache = LRU(100); // LRU cache with 100-item limit
169 If you want to clear the EJS cache, call `ejs.clearCache`. If you're using the
170 LRU cache and need a different limit, simple reset `ejs.cache` to a new instance
173 ## Custom file loader
175 The default file loader is `fs.readFileSync`, if you want to customize it, you can set ejs.fileLoader.
178 let ejs = require('ejs');
179 let myFileLoad = function (filePath) {
180 return 'myFileLoad: ' + fs.readFileSync(filePath);
183 ejs.fileLoader = myFileLoad;
186 With this feature, you can preprocess the template before reading it.
190 EJS does not specifically support blocks, but layouts can be implemented by
191 including headers and footers, like so:
195 <%- include('header') -%>
202 <%- include('footer') -%>
205 ## Client-side support
207 Go to the [Latest Release](https://github.com/mde/ejs/releases/latest), download
208 `./ejs.js` or `./ejs.min.js`. Alternately, you can compile it yourself by cloning
209 the repository and running `jake build` (or `$(npm bin)/jake build` if jake is
210 not installed globally).
212 Include one of these files on your page, and `ejs` should be available globally.
217 <div id="output"></div>
218 <script src="ejs.min.js"></script>
220 let people = ['geddy', 'neil', 'alex'],
221 html = ejs.render('<%= people.join(", "); %>', {people: people});
223 $('#output').html(html);
225 document.getElementById('output').innerHTML = html;
231 Most of EJS will work as expected; however, there are a few things to note:
233 1. Obviously, since you do not have access to the filesystem, `ejs.renderFile()` won't work.
234 2. For the same reason, `include`s do not work unless you use an `include callback`. Here is an example:
236 let str = "Hello <%= include('file', {person: 'John'}); %>",
237 fn = ejs.compile(str, {client: true});
239 fn(data, null, function(path, d){ // include callback
241 // d -> {person: 'John'}
242 // Put your code here
243 // Return the contents of file as a string
244 }); // returns rendered string
247 See the [examples folder](https://github.com/mde/ejs/tree/master/examples) for more details.
249 ### IDE Integration with Syntax Highlighting
251 VSCode:Javascript EJS by *DigitalBrainstem*
255 There are a number of implementations of EJS:
257 * TJ's implementation, the v1 of this library: https://github.com/tj/ejs
258 * Jupiter Consulting's EJS: http://www.embeddedjs.com/
259 * EJS Embedded JavaScript Framework on Google Code: https://code.google.com/p/embeddedjavascript/
260 * Sam Stephenson's Ruby implementation: https://rubygems.org/gems/ejs
261 * Erubis, an ERB implementation which also runs JavaScript: http://www.kuwata-lab.com/erubis/users-guide.04.html#lang-javascript
262 * DigitalBrainstem EJS Language support: https://github.com/Digitalbrainstem/ejs-grammar
266 Licensed under the Apache License, Version 2.0
267 (<http://www.apache.org/licenses/LICENSE-2.0>)
270 EJS Embedded JavaScript templates copyright 2112