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-square)](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 | ```html
|
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 | var 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` then the locals will be stored in the `locals` object. Set to `false` in strict mode.
|
75 | - `localsName` Name to use for the object storing local variables when not using `with` Defaults to `locals`
|
76 | - `rmWhitespace` Remove all safe-to-remove whitespace, including leading
|
77 | and trailing whitespace. It also enables a safer version of `-%>` line
|
78 | slurping for all scriptlet tags (it does not strip new lines of tags in
|
79 | the middle of a line).
|
80 | - `escape` The escaping function used with `<%=` construct. It is
|
81 | used in rendering and is `.toString()`ed in the generation of client functions. (By default escapes XML).
|
82 |
|
83 | This project uses [JSDoc](http://usejsdoc.org/). For the full public API
|
84 | documentation, clone the repository and run `npm run doc`. This will run JSDoc
|
85 | with the proper options and output the documentation to `out/`. If you want
|
86 | the both the public & private API docs, run `npm run devdoc` instead.
|
87 |
|
88 | ## Tags
|
89 |
|
90 | - `<%` 'Scriptlet' tag, for control-flow, no output
|
91 | - `<%_` 'Whitespace Slurping' Scriptlet tag, strips all whitespace before it
|
92 | - `<%=` Outputs the value into the template (escaped)
|
93 | - `<%-` Outputs the unescaped value into the template
|
94 | - `<%#` Comment tag, no execution, no output
|
95 | - `<%%` Outputs a literal '<%'
|
96 | - `%%>` Outputs a literal '%>'
|
97 | - `%>` Plain ending tag
|
98 | - `-%>` Trim-mode ('newline slurp') tag, trims following newline
|
99 | - `_%>` 'Whitespace Slurping' ending tag, removes all whitespace after it
|
100 |
|
101 | For the full syntax documentation, please see [docs/syntax.md](https://github.com/mde/ejs/blob/master/docs/syntax.md).
|
102 |
|
103 | ## Includes
|
104 |
|
105 | Includes either have to be an absolute path, or, if not, are assumed as
|
106 | relative to the template with the `include` call. For example if you are
|
107 | including `./views/user/show.ejs` from `./views/users.ejs` you would
|
108 | use `<%- include('user/show') %>`.
|
109 |
|
110 | You must specify the `filename` option for the template with the `include`
|
111 | call unless you are using `renderFile()`.
|
112 |
|
113 | You'll likely want to use the raw output tag (`<%-`) with your include to avoid
|
114 | double-escaping the HTML output.
|
115 |
|
116 | ```html
|
117 | <ul>
|
118 | <% users.forEach(function(user){ %>
|
119 | <%- include('user/show', {user: user}) %>
|
120 | <% }); %>
|
121 | </ul>
|
122 | ```
|
123 |
|
124 | Includes are inserted at runtime, so you can use variables for the path in the
|
125 | `include` call (for example `<%- include(somePath) %>`). Variables in your
|
126 | top-level data object are available to all your includes, but local variables
|
127 | need to be passed down.
|
128 |
|
129 | NOTE: Include preprocessor directives (`<% include user/show %>`) are
|
130 | still supported.
|
131 |
|
132 | ## Custom delimiters
|
133 |
|
134 | Custom delimiters can be applied on a per-template basis, or globally:
|
135 |
|
136 | ```javascript
|
137 | var ejs = require('ejs'),
|
138 | users = ['geddy', 'neil', 'alex'];
|
139 |
|
140 | // Just one template
|
141 | ejs.render('<?= users.join(" | "); ?>', {users: users}, {delimiter: '?'});
|
142 | // => 'geddy | neil | alex'
|
143 |
|
144 | // Or globally
|
145 | ejs.delimiter = '$';
|
146 | ejs.render('<$= users.join(" | "); $>', {users: users});
|
147 | // => 'geddy | neil | alex'
|
148 | ```
|
149 |
|
150 | ## Caching
|
151 |
|
152 | EJS ships with a basic in-process cache for caching the intermediate JavaScript
|
153 | functions used to render templates. It's easy to plug in LRU caching using
|
154 | Node's `lru-cache` library:
|
155 |
|
156 | ```javascript
|
157 | var ejs = require('ejs')
|
158 | , LRU = require('lru-cache');
|
159 | ejs.cache = LRU(100); // LRU cache with 100-item limit
|
160 | ```
|
161 |
|
162 | If you want to clear the EJS cache, call `ejs.clearCache`. If you're using the
|
163 | LRU cache and need a different limit, simple reset `ejs.cache` to a new instance
|
164 | of the LRU.
|
165 |
|
166 | ## Custom FileLoader
|
167 |
|
168 | The default file loader is `fs.readFileSync`, if you want to customize it, you can set ejs.fileLoader.
|
169 |
|
170 | ```javascript
|
171 | var ejs = require('ejs');
|
172 | var myFileLoad = function (filePath) {
|
173 | return 'myFileLoad: ' + fs.readFileSync(filePath);
|
174 | };
|
175 |
|
176 | ejs.fileLoader = myFileLoad;
|
177 | ```
|
178 |
|
179 | With this feature, you can preprocess the template before reading it.
|
180 |
|
181 | ## Layouts
|
182 |
|
183 | EJS does not specifically support blocks, but layouts can be implemented by
|
184 | including headers and footers, like so:
|
185 |
|
186 |
|
187 | ```html
|
188 | <%- include('header') -%>
|
189 | <h1>
|
190 | Title
|
191 | </h1>
|
192 | <p>
|
193 | My page
|
194 | </p>
|
195 | <%- include('footer') -%>
|
196 | ```
|
197 |
|
198 | ## Client-side support
|
199 |
|
200 | Go to the [Latest Release](https://github.com/mde/ejs/releases/latest), download
|
201 | `./ejs.js` or `./ejs.min.js`. Alternately, you can compile it yourself by cloning
|
202 | the repository and running `jake build` (or `$(npm bin)/jake build` if jake is
|
203 | not installed globally).
|
204 |
|
205 | Include one of these files on your page, and `ejs` should be available globally.
|
206 |
|
207 | ### Example
|
208 |
|
209 | ```html
|
210 | <div id="output"></div>
|
211 | <script src="ejs.min.js"></script>
|
212 | <script>
|
213 | var people = ['geddy', 'neil', 'alex'],
|
214 | html = ejs.render('<%= people.join(", "); %>', {people: people});
|
215 | // With jQuery:
|
216 | $('#output').html(html);
|
217 | // Vanilla JS:
|
218 | document.getElementById('output').innerHTML = html;
|
219 | </script>
|
220 | ```
|
221 |
|
222 | ### Caveats
|
223 |
|
224 | Most of EJS will work as expected; however, there are a few things to note:
|
225 |
|
226 | 1. Obviously, since you do not have access to the filesystem, `ejs.renderFile()` won't work.
|
227 | 2. For the same reason, `include`s do not work unless you use an `IncludeCallback`. Here is an example:
|
228 | ```javascript
|
229 | var str = "Hello <%= include('file', {person: 'John'}); %>",
|
230 | fn = ejs.compile(str, {client: true});
|
231 |
|
232 | fn(data, null, function(path, d){ // IncludeCallback
|
233 | // path -> 'file'
|
234 | // d -> {person: 'John'}
|
235 | // Put your code here
|
236 | // Return the contents of file as a string
|
237 | }); // returns rendered string
|
238 | ```
|
239 |
|
240 | ## Related projects
|
241 |
|
242 | There are a number of implementations of EJS:
|
243 |
|
244 | * TJ's implementation, the v1 of this library: https://github.com/tj/ejs
|
245 | * Jupiter Consulting's EJS: http://www.embeddedjs.com/
|
246 | * EJS Embedded JavaScript Framework on Google Code: https://code.google.com/p/embeddedjavascript/
|
247 | * Sam Stephenson's Ruby implementation: https://rubygems.org/gems/ejs
|
248 | * Erubis, an ERB implementation which also runs JavaScript: http://www.kuwata-lab.com/erubis/users-guide.04.html#lang-javascript
|
249 |
|
250 | ## License
|
251 |
|
252 | Licensed under the Apache License, Version 2.0
|
253 | (<http://www.apache.org/licenses/LICENSE-2.0>)
|
254 |
|
255 | - - -
|
256 | EJS Embedded JavaScript templates copyright 2112
|
257 | mde@fleegix.org.
|
258 |
|
\ | No newline at end of file |