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#info=devDependencies)
|
7 |
|
8 | ## Installation
|
9 |
|
10 | ```bash
|
11 | $ npm install ejs
|
12 | ```
|
13 |
|
14 | ## Features
|
15 |
|
16 | * Control flow with `<% %>`
|
17 | * Escaped output with `<%= %>`
|
18 | * Unescaped raw output with `<%- %>`
|
19 | * Trim-mode ('newline slurping') with `-%>` ending tag
|
20 | * Custom delimiters (e.g., use '<? ?>' instead of '<% %>')
|
21 | * Includes
|
22 | * Client-side support
|
23 | * Static caching of intermediate JavaScript
|
24 | * Static caching of templates
|
25 | * Complies with the [Express](http://expressjs.com) view system
|
26 |
|
27 | ## Example
|
28 |
|
29 | ```html
|
30 | <% if (user) { %>
|
31 | <h2><%= user.name %></h2>
|
32 | <% } %>
|
33 | ```
|
34 |
|
35 | ## Usage
|
36 |
|
37 | ```javascript
|
38 | var template = ejs.compile(str, options);
|
39 | template(data);
|
40 | // => Rendered HTML string
|
41 |
|
42 | ejs.render(str, data, options);
|
43 | // => Rendered HTML string
|
44 | ```
|
45 |
|
46 | You can also use the shortcut `ejs.render(dataAndOptions);` where you pass
|
47 | everything in a single object. In that case, you'll end up with local variables
|
48 | for all the passed options.
|
49 |
|
50 | ## Options
|
51 |
|
52 | - `cache` Compiled functions are cached, requires `filename`
|
53 | - `filename` Used by `cache` to key caches, and for includes
|
54 | - `context` Function execution context
|
55 | - `compileDebug` When `false` no debug instrumentation is compiled
|
56 | - `client` Returns standalone compiled function
|
57 | - `delimiter` Character to use with angle brackets for open/close
|
58 | - `debug` Output generated function body
|
59 | - `_with` Whether or not to use `with() {}` constructs. If `false`
|
60 | then the locals will be stored in the `locals` object.
|
61 |
|
62 | ## Tags
|
63 |
|
64 | - `<%` 'Scriptlet' tag, for control-flow, no output
|
65 | - `<%=` Outputs the value into the template (HTML escaped)
|
66 | - `<%-` Outputs the unescaped value into the template
|
67 | - `<%#` Comment tag, no execution, no output
|
68 | - `<%%` Outputs a literal '<%'
|
69 | - `%>` Plain ending tag
|
70 | - `-%>` Trim-mode ('newline slurp') tag, trims following newline
|
71 |
|
72 | ## Includes
|
73 |
|
74 | Includes are relative to the template with the `include` call. (This
|
75 | requires the 'filename' option.) For example if you have "./views/users.ejs" and
|
76 | "./views/user/show.ejs" you would use `<%- include('user/show'); %>`.
|
77 |
|
78 | You'll likely want to use the raw output tag (`<%-`) with your include to avoid
|
79 | double-escaping the HTML output.
|
80 |
|
81 | ```html
|
82 | <ul>
|
83 | <% users.forEach(function(user){ %>
|
84 | <%- include('user/show', {user: user}); %>
|
85 | <% }); %>
|
86 | </ul>
|
87 | ```
|
88 |
|
89 | Includes are inserted at runtime, so you can use variables for the path in the
|
90 | `include` call (for example `<%- include(somePath); %>`). Variables in your
|
91 | top-level data object are available to all your includes, but local variables
|
92 | need to be passed down.
|
93 |
|
94 | NOTE: Include preprocessor directives (`<% include user/show %>`) are
|
95 | still supported.
|
96 |
|
97 | ## Custom delimiters
|
98 |
|
99 | Custom delimiters can be applied on a per-template basis, or globally:
|
100 |
|
101 | ```javascript
|
102 | var ejs = require('ejs'),
|
103 | users = ['geddy', 'neil', 'alex'];
|
104 |
|
105 | // Just one template
|
106 | ejs.render('<?= users.join(" | "); ?>', {users: users}, {delimiter: '?'});
|
107 | // => 'geddy | neil | alex'
|
108 |
|
109 | // Or globally
|
110 | ejs.delimiter = '$';
|
111 | ejs.render('<$= users.join(" | "); $>', {users: users});
|
112 | // => 'geddy | neil | alex'
|
113 | ```
|
114 |
|
115 | ## Layouts
|
116 |
|
117 | EJS does not specifically support blocks, but layouts can be implemented by
|
118 | including headers and footers, like so:
|
119 |
|
120 |
|
121 | ```html
|
122 | <%- include('header'); -%>
|
123 | <h1>
|
124 | Title
|
125 | </h1>
|
126 | <p>
|
127 | My page
|
128 | </p>
|
129 | <%- include('footer'); -%>
|
130 | ```
|
131 |
|
132 | ## Client-side support
|
133 |
|
134 | Go to the [Latest Release](https://github.com/mde/ejs/releases/latest), download
|
135 | `./ejs.js` or `./ejs.min.js`.
|
136 |
|
137 | Include one of these on your page, and `ejs.render(str)`.
|
138 |
|
139 | ## Related projects
|
140 |
|
141 | There are a number of implementations of EJS:
|
142 |
|
143 | * TJ's implementation, the v1 of this library: https://github.com/tj/ejs
|
144 | * Jupiter Consulting's EJS: http://www.embeddedjs.com/
|
145 | * EJS Embedded JavaScript Framework on Google Code: https://code.google.com/p/embeddedjavascript/
|
146 | * Sam Stephenson's Ruby implementation: https://rubygems.org/gems/ejs
|
147 | * Erubis, an ERB implementation which also runs JavaScript: http://www.kuwata-lab.com/erubis/users-guide.04.html#lang-javascript
|
148 |
|
149 | ## License
|
150 |
|
151 | Licensed under the Apache License, Version 2.0
|
152 | (<http://www.apache.org/licenses/LICENSE-2.0>)
|
153 |
|
154 | - - -
|
155 | EJS Embedded JavaScript templates copyright 2112
|
156 | mde@fleegix.org.
|
157 |
|
158 |
|