Extending Wjst

Custom Filters

Filters are simply functions that perform transformations on their first input argument.

Filters are run at render time, so they may not directly modify the compiled template structure in any way.

All of Wjst's built-in filters are written in this same way. For more examples, reference the `filters.js` file in Wjst's source.

To disable auto-escaping on a custom filter, simply add a property to the filter method `safe = true;` and the output from this will not be escaped, no matter what the global settings are for Wjst.

Arguments

// This filter will return 'bazbop' if the idx on the input is not 'foobar'
wjst.setFilter('foobar', function (input, idx) {
  return input[idx] === 'foobar' ? input[idx] : 'bazbop';
});
// myvar = ['foo', 'bar', 'baz', 'bop'];
// => {{ myvar|foobar(3) }}
// Since myvar[3] !== 'foobar', we render:
// => bazbop

// This filter will disable auto-escaping on its output:
function bazbop (input) { return input; }
bazbop.safe = true;
wjst.setFilter('bazbop', bazbop);
// => {{ "<p>"|bazbop }}
// => <p>

Custom Tags

Wjst can be extended to handle custom tags that will perform operations on full blocks of your templates. Use wjst.setTag(name, parse, compile, ends, blockLevel) to add your custom tag.

All of Wjst's tags are written using the same api (with a few exceptions for core modules, like extends and block). View a tag's source to see more examples to write your own custom tags.

parse(str, line, parser, types, stack, options, wjst)

Define custom parsing methods for your tag.

Arguments

exports.parse = function (str, line, parser, types, options, swig) {
parser.on('start', function () {
// ...
});
parser.on(types.STRING, function (token) {
// ...
});
};

compile(compiler, args, content, parents, options, blockName)

Compile callback for VarToken and TagToken objects.

Arguments

exports.compile = function (compiler, args, content, parents, options, blockName) {
if (args[0] === 'foo') {
return compiler(content, parents, options, blockName) + '\n';
}
return '_output += "fallback";\n';
};

ends

Controls whether or not a tag must have an {% end[tagName] %} declared after usage in templates.

exports.ends = true;
// => A template that fails to close this tag will throw an Error.

exports.ends = false;
// => A template attempts close this tag will throw an Error.

blockLevel

Allow the tag to be written outside of {% block <name> %}{% endblock %} tags when extending a parent template.

exports.blockLevel = true;

{% extends "foo" %}
{% mytag foo bar baz %}
// Normally this will be ignored, but since we allowed it to be block-level,
// it will be included in the fully-parsed template.
				
{% block content %}
...
{% endblock %}

TYPES

Enum for token types.