README.md (9683B)
1 # EJS 2 3 Embedded JavaScript templates 4 5 [](https://travis-ci.org/mde/ejs) 6 [](https://david-dm.org/mde/ejs?type=dev) 7 [](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.