ejs-html
v5.1.5
Published
Embedded JavaScript HTML templates. An implementation of EJS focused on run-time performance, HTML syntax checking, minified HTML output and custom HTML elements.
Downloads
954
Readme
EJS HTML
Embedded JavaScript HTML templates. An implementation of EJS focused on run-time performance, HTML syntax checking, minified HTML output and custom HTML elements.
Usage
npm install ejs-html --save
let ejs = require('ejs-html')
let html = ejs.render('<input type="text" disabled="<%=disabled%>" value="<%=value%>" />', {
disabled: false,
value: 'hi you'
}, {
vars: ['disabled', 'value']
})
// html = '<input type=text value="hi you">'
Why another EJS implementation?
This module is inspired by EJS, and is a subset of its syntax, focused on giving HTML first-class support. That is, not all EJS are valid EJS-HTML. Most features listed bellow are possible only with an HTML-aware parser.
Check their excellent site for EJS-specific docs and tutorials.
Strictly speaking, this is not even EJS (details bellow).
Breaking changes in v5
Old versions compiled to sloppy mode and used the with(locals)
block by default.
That allowed one to write <%= a %>
instead of <%= locals.a %>
but had more unwanted consequences.
Read more about what changed and how to opt-out from the change in HISTORY.md.
Features
Compile-time HTML minification
The template source is parsed and minified on compile time, so there is no impact on render-time. The minification applies these rules:
- Collapse text whitespace:
<b>Hello\n\t you</b>
is transformed to<b>Hello\nyou</b>
- Remove attribute quotes:
<div class="alert">
→<div class=alert>
- Normalize attributes spaces:
<input \n required>
→<input required>
- Normalize class spaces:
<div class=" a b ">
→<div class="a b">
- Simplify boolean attributes:
<input required="oh-yeah!">
→<input required>
- Remove self-close slash:
<br />
→<br>
Render-time error mapping
Errors during render-time are mapped back to their original source location (that is, we keep an internal source map)
ejs.render(`<select>
<% for (let option of locals.options) { %>
<option value="<%= option.value %>">
<%= option.text %>
</option>
<% } %>
</select>`, {
options: [null]
})
TypeError: ejs:3
1 | <select>
2 | <% for (let option of options) { %>
3 >> | <option value="<%= option.value %>">
4 | <%= option.text %>
5 | </option>
Cannot read property 'value' of null
at eval (eval at module.exports (D:\Programs\ejs-html\lib\compile.js:45:20), <anonymous>:4:51)
at D:\Programs\ejs-html\lib\compile.js:64:11
at Object.module.exports.render (D:\Programs\ejs-html\index.js:12:48)
Boolean attributes
Attributes like disabled
and checked
are recognized as boolean. So one may write disabled=<%=disabled%>
instead of <%if(disabled){%>disabled<%}%>
, as one must in plain EJS.
This is one point that makes EJS-HTML not EJS-compliant. In EJS, any literal text is outputed as is. In the example above this is not what happens: the text disabled=
is not outputed if the local value disabled
is falsy, since ejs-html knows this is a boolean attribute.
Server-side compiled, client-side rendered
Compile the template server-side and export a function to render it in the client-side.
Extensible semantics
Transformers may be registered to change the parsed elements tree and implement custom semantics.
For example:
// change I elements for EM
var render = ejs.compile('<i>Hi</i> <p><i>Deep</i></p>', {
transformer: function translate(tokens) {
tokens.forEach(token => {
if (token.type === 'element') {
if (token.name === 'i') {
token.name = 'em'
}
translate(token.children)
}
})
}
})
render() // '<em>Hi</em> <p><em>Deep</em></p>'
Custom elements
Unleash the semantic power of HTML with custom elements. To use custom elements you must first define one:
For example, define your own confirm dialog (in dialog.ejs
):
<div class="dialog">
<div class="dialog-title">
<%= title %>
<% if (closable) { %>
<div class="dialog-close">X</div>
<% } %>
</div>
<eh-placeholder>
<!-- dialog content goes here -->
</eh-placeholder>
<div class="dialog-buttons">
<button class="dialog-yes">Yes</button>
<button class="dialog-no">No</button>
</div>
</div>
And then use it, like:
<custom-dialog title="Wanna Know?" closable>
<em>HTML</em> Content
</custom-dialog>
The attributes on the custom-dialog
tag is passed as locals to dialog.ejs
and its content replaces the <eh-placeholder></eh-placeholder>
tag.
Custom elements is a more powerful replacement for ejs' include feature.
This is the most basic usage of this feature. For more (like passing JS values and multiple content areas), see custom-els.md
Source maps
Compile with support for source map generation (requires node >= v8, since source-map
has dropped support for older versions)
let fn = ejs.compile('Hello <%= locals.world %>', {sourceMap: true})
// The actual result may vary
fn.code // "use strict";locals=locals||{};let __c=locals.__contents||{};return "Hello "+(__l.s=__l.e=1,__e(locals.world));
fn.map // {"version":3,"sources":["ejs"],"names":[],"mappings":"gGAAU,Y","file":"ejs.js"}
fn.mapWithCode // {"version":3,"sources":["ejs"],"names":[],"mappings":"gGAAU,Y","file":"ejs.js","sourcesContent":["Hello <%= locals.world %>"]}
Missing features
The following list of features are supported in other EJS implementations, but not by this one (at least, yet):
- No support for custom delimiters
- No caching
- No built-in express support
- No include: use custom elements instead
API
The main API is the compile
function. Everything else is auxiliary.
compile(source[, options])
Compile the given EJS-HTML source into a render function. options
is an optional object, with the following optional keys:
compileDebug
: iffalse
, no extended context will be added to exceptions thrown at runtime (defaults totrue
). Iftrue
, the compiled code will be larger and will include the original EJS sourcefilename
: used to name the file in render-time error's stack tracetransformer
: a function that can transform the parsed HTML element tree, before the minification and compilation. This should return a new array of tokens orundefined
to use the same (in case of in-place changes). Consult the definition of aToken
in the parse.js file.strictMode
: iffalse
, use sloppy mode and wrap the code in awith(locals) {}
block (defaults totrue
).vars
: an array of var names that will be exposed fromlocals
(defaults to[]
).sourceMap
: iftrue
, create and return the source map
This will return a compiled render function that can then be called like: render(locals[, renderCustom])
. locals
is the data object used to fill the template. renderCustom
is an optional function used to render custom elements, see custom-els.md for more info about it.
The returned function has three extra properties if sourceMap
is active:
fn.code
: compiled JS codefn.map
: source map without the source codefn.mapWithCode
: source map with the source code
compile.standAlone(source[, options])
Like compile()
, but returns the function body code as a string, so that it can be exported somewhere else. A use case for this is compile the EJS template in the server, export the function to the client and render in the browser:
// On the server
let functionBody = ejs.compile.standAlone('<p>Hi <%=name%></p>', {vars: ['name']})
// On the client
var render = new Function('locals, renderCustom', functionBody)
render({name: 'you'}) // <p>Hi you</p>
compile.standAloneAsObject(source[, options])
Like compile.standAlone()
, but returns an object with three properties:
obj.code
: the compiled code, the same value returned bycompile.standAlone()
obj.map
andobj.mapWithCode
: extra properties whensourceMap
option is active
render(source[, locals[, options]])
Just a convinience for compile(source, options)(locals)
.
parse(source)
Parse the given EJS-HTML source into a array of tokens. Use for low-level, crazy thinks (like some internal tooling).
reduce(tokens[, options])
Remove comments, transform fixed tokens back to text and apply HTML minification. Use for low-level, crazy things.
escape.html(str)
Return a HTML-safe version of str
, escaping &, <, >, " and '
escape.js(str)
Escape as to make safe to put inside double quotes: x = "..."
, escaping , \n, \r and "
escape.getSnippet(source, lineStart, lineEnd)
Extract the code snippet in the given region (used internally to create error messages)