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