Embedded JavaScript templates


Embedded JavaScript templates

$ npm install ejs
  • Control flow with <% %>
  • Escaped output with <%= %>
  • Unescaped raw output with <%- %>
  • Trim-mode ('newline slurping') with -%> ending tag
  • Custom delimiters (e.g., use '' instead of '<% %>')
  • Includes
  • Client-side support
  • Static caching of intermediate JavaScript
  • Static caching of templates
  • Complies with the Express view system
<% if (user) { %>
  <h2><%= user.name %></h2>
<% } %>
var template = ejs.compile(str, options);
// => Rendered HTML string 
ejs.render(str, data, options);
// => Rendered HTML string 

You can also use the shortcut ejs.render(dataAndOptions); where you pass everything in a single object. In that case, you'll end up with local variables for all the passed options.

  • cache Compiled functions are cached, requires filename
  • filename Used by cache to key caches, and for includes
  • context Function execution context
  • compileDebug When false no debug instrumentation is compiled
  • client Returns standalone compiled function
  • delimiter Character to use with angle brackets for open/close
  • debug Output generated function body
  • _with Whether or not to use with() {} constructs. If false then the locals will be stored in the locals object.
  • rmWhitespace Remove all safe-to-remove whitespace, including leading and trailing whitespace. It also enables a safer version of -%> line slurping for all scriptlet tags (it does not strip new lines of tags in the middle of a line).
  • <% 'Scriptlet' tag, for control-flow, no output
  • <%= Outputs the value into the template (HTML escaped)
  • <%- Outputs the unescaped value into the template
  • <%# Comment tag, no execution, no output
  • <%% Outputs a literal '<%'
  • %> Plain ending tag
  • -%> Trim-mode ('newline slurp') tag, trims following newline

Includes are relative to the template with the include call. (This requires the 'filename' option.) For example if you have "./views/users.ejs" and "./views/user/show.ejs" you would use <%- include('user/show'); %>.

You'll likely want to use the raw output tag (<%-) with your include to avoid double-escaping the HTML output.

  <% users.forEach(function(user){ %>
    <%- include('user/show', {user: user}); %>
  <% }); %>

Includes are inserted at runtime, so you can use variables for the path in the include call (for example <%- include(somePath); %>). Variables in your top-level data object are available to all your includes, but local variables need to be passed down.

NOTE: Include preprocessor directives (<% include user/show %>) are still supported.

Custom delimiters can be applied on a per-template basis, or globally:

var ejs = require('ejs'),
    users = ['geddy', 'neil', 'alex'];
// Just one template 
ejs.render('<?= users.join(" | "); ?>', {users: users}, {delimiter: '?'});
// => 'geddy | neil | alex' 
// Or globally 
ejs.delimiter = '$';
ejs.render('<$= users.join(" | "); $>', {users: users});
// => 'geddy | neil | alex' 

EJS ships with a basic in-process cache for caching the intermediate JavaScript functions used to render templates. It's easy to plug in LRU caching using Node's lru-cache library:

var ejs = require('ejs')
  , LRU = require('lru-cache');
ejs.cache = LRU(100); // LRU cache with 100-item limit 

If you want to clear the EJS cache, call ejs.clearCache. If you're using the LRU cache and need a different limit, simple reset ejs.cache to a new instance of the LRU.

EJS does not specifically support blocks, but layouts can be implemented by including headers and footers, like so:

<%- include('header'); -%>
  My page
<%- include('footer'); -%>

Go to the Latest Release, download ./ejs.js or ./ejs.min.js.

Include one of these on your page, and ejs.render(str).

There are a number of implementations of EJS:

  • TJ's implementation, the v1 of this library: https://github.com/tj/ejs
  • Jupiter Consulting's EJS: http://www.embeddedjs.com/
  • EJS Embedded JavaScript Framework on Google Code: https://code.google.com/p/embeddedjavascript/
  • Sam Stephenson's Ruby implementation: https://rubygems.org/gems/ejs
  • Erubis, an ERB implementation which also runs JavaScript: http://www.kuwata-lab.com/erubis/users-guide.04.html#lang-javascript

Licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

EJS Embedded JavaScript templates copyright 2112 mde@fleegix.org.