node_modules/ejs/README.md

   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 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   - `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.
  89
  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.
  94
  95 ## Tags
  96
  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
 107
 108 For the full syntax documentation, please see [docs/syntax.md](https://github.com/mde/ejs/blob/master/docs/syntax.md).
 109
 110 ## Includes
 111
 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') %>`.
 116
 117 You must specify the `filename` option for the template with the `include`
 118 call unless you are using `renderFile()`.
 119
 120 You'll likely want to use the raw output tag (`<%-`) with your include to avoid
 121 double-escaping the HTML output.
 122
 123 ```html
 124 <ul>
 125   <% users.forEach(function(user){ %>
 126     <%- include('user/show', {user: user}) %>
 127   <% }); %>
 128 </ul>
 129 ```
 130
 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.
 135
 136 NOTE: Include preprocessor directives (`<% include user/show %>`) are
 137 still supported.
 138
 139 ## Custom delimiters
 140
 141 Custom delimiters can be applied on a per-template basis, or globally:
 142
 143 ```javascript
 144 let ejs = require('ejs'),
 145     users = ['geddy', 'neil', 'alex'];
 146
 147 // Just one template
 148 ejs.render('<?= users.join(" | "); ?>', {users: users}, {delimiter: '?'});
 149 // => 'geddy | neil | alex'
 150
 151 // Or globally
 152 ejs.delimiter = '$';
 153 ejs.render('<$= users.join(" | "); $>', {users: users});
 154 // => 'geddy | neil | alex'
 155 ```
 156
 157 ## Caching
 158
 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:
 162
 163 ```javascript
 164 let ejs = require('ejs'),
 165     LRU = require('lru-cache');
 166 ejs.cache = LRU(100); // LRU cache with 100-item limit
 167 ```
 168
 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
 171 of the LRU.
 172
 173 ## Custom file loader
 174
 175 The default file loader is `fs.readFileSync`, if you want to customize it, you can set ejs.fileLoader.
 176
 177 ```javascript
 178 let ejs = require('ejs');
 179 let myFileLoad = function (filePath) {
 180   return 'myFileLoad: ' + fs.readFileSync(filePath);
 181 };
 182
 183 ejs.fileLoader = myFileLoad;
 184 ```
 185
 186 With this feature, you can preprocess the template before reading it.
 187
 188 ## Layouts
 189
 190 EJS does not specifically support blocks, but layouts can be implemented by
 191 including headers and footers, like so:
 192
 193
 194 ```html
 195 <%- include('header') -%>
 196 <h1>
 197   Title
 198 </h1>
 199 <p>
 200   My page
 201 </p>
 202 <%- include('footer') -%>
 203 ```
 204
 205 ## Client-side support
 206
 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).
 211
 212 Include one of these files on your page, and `ejs` should be available globally.
 213
 214 ### Example
 215
 216 ```html
 217 <div id="output"></div>
 218 <script src="ejs.min.js"></script>
 219 <script>
 220   let people = ['geddy', 'neil', 'alex'],
 221       html = ejs.render('<%= people.join(", "); %>', {people: people});
 222   // With jQuery:
 223   $('#output').html(html);
 224   // Vanilla JS:
 225   document.getElementById('output').innerHTML = html;
 226 </script>
 227 ```
 228
 229 ### Caveats
 230
 231 Most of EJS will work as expected; however, there are a few things to note:
 232
 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:
 235   ```javascript
 236   let str = "Hello <%= include('file', {person: 'John'}); %>",
 237       fn = ejs.compile(str, {client: true});
 238
 239   fn(data, null, function(path, d){ // include callback
 240     // path -> 'file'
 241     // d -> {person: 'John'}
 242     // Put your code here
 243     // Return the contents of file as a string
 244   }); // returns rendered string
 245   ```
 246
 247 See the [examples folder](https://github.com/mde/ejs/tree/master/examples) for more details.
 248
 249 ### IDE Integration with Syntax Highlighting
 250
 251 VSCode:Javascript EJS by *DigitalBrainstem*
 252
 253 ## Related projects
 254
 255 There are a number of implementations of EJS:
 256
 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
 263
 264 ## License
 265
 266 Licensed under the Apache License, Version 2.0
 267 (<http://www.apache.org/licenses/LICENSE-2.0>)
 268
 269 - - -
 270 EJS Embedded JavaScript templates copyright 2112
 271 mde@fleegix.org.