wash

Wash

A safe template rendering engine for Node.

Tutorial

A short sample code first:

var wash = require('wash');

var source = 
  'My name is {{ name }}. I am {{ age }} years old.\n' +
  '{% if age > 20 %}(Yes I am old enough.){% endif %}\n' +
  'I have {{ len(kids) }} kids. They are {{ join(kids, ", ") }}.\n' +
  'THEY ARE {% for k in kids %}{{ upper(k.value) }} {% endfor %}';

var context = {
  name: 'John',
  age: 30,
  kids: ['Daniel', 'Paul', 'Mark']
};

var output = wash.render(source, context);

console.log(output);

Output will look like this.

My name is John. I am 30 years old.
(Yes I am old enough.)
I have 3 kids. They are Daniel, Paul, Mark.
THEY ARE DANIEL PAUL MARK 

So, basically, what wash does here is to render the input source string with the provided context variables.

• {{ name }} prints out the value of name variable (context.name). It becomes John in this example.
• {{ age }} does the same to age variable. But this time it's a number.
• {% if age > 20 %} ... {% endif %} prints (or execute) the string between if and endif tags only when name is above 20.
• {{ len(kids) }} prints the number of elements in kids collection. The collection can be an array or an object. In this example, kids is an array with 3 string elements. So this outputs 3.
• {{ join(kids, ", ") }} joins the elements of kids using separator of ", ".
• {% for k in kids %} ... {% endfor %} iterates kids collection. Inside this loop, you can access each element using k variable. So, {{ k.value }} evaluates to the value of the current element.
• {{ upper(k.value) }} converts the value of k to uppercase characters.

For more details on the template syntax, please see Template Syntax below.

Why Wash?

Wash is safe. You can run untrusted template codes in Wash.

• Wash doew not allow the template code to access external variables, modules, or functions.
• (work in progress) Wash can restrict the number of iterations or the number of elements in collection.

References

The first thing you need to do is to get a Wash module.

var wash = require('wash');

wash.render(source, context)

This compiles source, render with context, and returns output string.

var source = '{{ foo }}';
var context = { foo: 'bar' };
console.log(wash.render(source, context)); // prints "bar"

You can also pass the precompiled object (that was returned from wash.precompile() function) as source parameter.

var source = '{{ foo }}';
var context = { foo: 'bar' };
var precompiled = wash.precompile(source);
console.log(wash.render(precompiled, context)); // prints "bar"

wash.precompile(source)

This pre-compiles the source, and, returns a Precompiled object which contains:

• code: pre-compiled JavaScript code
• render(context): function to render with the context

To render using the precompiled code, you can simple call its render(context) function.

var source = '{{ foo }}';
var context = { foo: 'bar' };
var precompiled = wash.precompile(source);
console.log(precompiled.code); // prints some JavaScript code lines
console.log(precompiled.render(context)); // prints "bar"

Or, you can pass the Precompiled object to wash.render() function as shown above.

wash.save(precompiled)

This returns a string from the precompiled object so you can re-use the Precompiled object using wash.load() function.

var source = '{{ foo }}';
var context = { foo: 'bar' };
var precompiled = wash.precompile(source);
var cachableString = wash.save(precompiled);

wash.load(savedPrecompiled)

This re-construct a Precompiled object from the saved string using wash.save() function so you can re-use it multiple times.

var cachedString = /* should be a string created by wash.save() function */;
var precompiled = wash.load(cachedString);

var context = { foo: 'bar' };
console.log(precompiled.render(context)); // prints "some outputs"

wash.setOption(name, value)

This sets a Wash option. See Options for more detail.

wash.setOption('throwsOnErrors', true);

wash.getOption(name)

This returns the current value of option named name. See Options for more detail.

wash.resetOptions()

This resets all options to the default values. See Options for more detail.

Template Syntax

Expressions

You can construct expressions using the following elements.

• Literals: "texts", numbers, true, false
• Operators: +, -, *, /, ==, !=, >=, <=, >, <, ||, &&, !
• Parenthesis: (, )
• Variables: those provided as a context parameter to rendering functions

Evaluation

{{ expression }}

Evaluates expression and replace with the outcome.

var wash = require('wash');
var output = wash.render('{{ foo }}', { foo: 'bar' }));
assert(output === 'bar');

Conditional

{% if expression %} {% elif expression %} {% else %} {% endif %}

Run the code conditionally. Wash follows the commonly used approaches here:

{% if expr1 %}
  executed when expr1 is true.
{% elif expr2 %}
  executed when expr1 was false and expr2 is true.
{% elif ... %}
  ...
{% elif exprN %}
  executed when expr1, expr2, ... exprN-1 were all false and exprN is true.
{% else %}
  executed when expr1, expr2, ... exprN were all false.
{% endif %}

Nested conditionals are also allowed.

Loop

{% for var in expression %} {% endfor %}

You can iterate over a collection, expression. The collection can be an object. If the collection is an array, Wash internally convert it to an object with indices as its keys.

You can access the current element using var object, which contains the following properties.

• key: the key name of property
• value: the value of property
• index: an index starting from 0
• (work in progress) isFirst: true if it is the first element
• (work in progress) isLast: true if it is the last element

Nested loops are also allowed.

Built-in Functions

• range(start, stop, step)
• lower(str)
• upper(str)
• join(collection, delim)
• len(collection)
• reverse(collection)
• sort(collection, reverse)
• isArray(x)
• isObject(x)
• slice(collection, start, stop)

Options

throwsOnErrors

• true: an exception will be thrown if an error occurs while precompiling or rendering.
• false: (default) errors are simply ignored.

Wash in Production

• gist.sh: (currently in beta phase)

License

MIT license