soywiz-archive / atpl.js

A complete and fast template engine fully compatible with twig for node.js.

Build status on Travis:

Install with NPM:

npm install atpl

Using with express3:

app.engine('html', require('atpl').__express);
app.set('devel', false);
app.set('view engine', 'html');
app.set('view cache', true);
app.set('views', __dirname + '/templates');

app.get('/simple', function(req, res) {
	res.render('simple', { name : 'Test' });
});

Using as standalone:

var atpl = require('atpl');
console.log(atpl.renderFileSync(__dirname + '/views', 'simple.html', { name: 'MyName' }, false));
atpl.renderFile(__dirname + '/views', 'simple.html', { name: 'MyName' }, false), function(err, result) {
	console.log(result);
});

Typescript typings: https://github.com/soywiz/atpl.js/blob/master/lib/atpl.d.ts

This project is designed to be compatible with twig. So the documentation about tags, filters, functions and tests is on the twig page:

• http://twig.sensiolabs.org/documentation

I have continued working on it because there are several projects implementing twig templates but they are not implemented very well and lacks stuff like multiple inheritance or nesting blocks, or are slow because doesn't perform dynamic recompilation.

This project will implement the full twig set and will be as fast as possible.

Supported syntax:

• Inheritance
• Conditional inheritance
• Include
• if+elseif+else
• for+else+loop scope variable
• Auto-escape
• Escape (|e) (|e('js')) (|e('css'))...
• Skip autoescape (|raw)
• Filters (all twig filters but 'convert_encoding' that is not required because javascript strings are unicode)
• Functions (all twig functions but 'constant')
• Tests (all twig tests but 'constant')
• Tags (all twig tags)
• value in array
• value in string
• set a, b = 'a', 'b'
• macro support (macro+import+from)
• sandbox
• use (horizontal reuse)

{% autoescape %}
{% autoescape 'type' %}
{% extends "file.atpl" %}
{% extends cond ? "base1" : "base2" %}
{% include "template" %}
{% include "template" with { 'foo' : 'bar' } only %}
{% block name %}...{% endblock %}
{% for var in list %}...{% endfor %}
{% for var in list %}...{% else %}...{% endfor %}
{% for key, value in list %}...{% else %}...{% endfor %}
{% for key, value in list if condition %}...{% else %}...{% endfor %}
{% for key in ['a', 'b', 'c'] %}{{ loop.index0 }}{% endfor %}
{% if condition %}...{% else %}...{% endif %}
{% if cond1 %}...{% elseif cond2 %}...{% else %}...{% endif %}
{% set a, b = 'a', 'b' %}
{{ expression }}
{{ expression|filter }}
{{ expression|filter(params) }}
{{ function(params) }}
{{ var is even }}
{{ var is not defined }}
{{ var is sameas(var) }}
{{ var.array['access'] }}
{{ 3 in [1, 2, 3, 4] }}
{{ {'key':'value','key2':'value2'} }}

atpl.js's Issues

Are macros supported?

this code doesn't work

{% macro test() %}
    1
{% endmacro %}

{{ _self.test() }}

test empty refinements

As noticed in #18:

empty returns true only if the variable is undefined or null, should return true when null, false, an empty array, or the empty string.

dump function - multiple variables

{{ dump(a, b) }} dumps only first variable, but in twig dump function dumps all variables
http://twig.sensiolabs.org/doc/functions/dump.html

do tag

As noticed in #18

Support slice operator

http://twig.sensiolabs.org/doc/filters/slice.html

Implement "is null" test

As noticed in #18

is null doesn't work

_context variable

Working with twig (in Symfony) sometimes it was hard to guess which variables are available in template, but twig has an _context variable, so {{ _context | keys }} return all variables names.

Is it possibleto add _context variable to atpl?

raw implementation

Hello, from what I see in the description raw is not implemented, is that on plans?

Thanks!

split filter

As noticed in #18

replace filter

As noticed in #18

Short ternary operator

Is it possible to add a "short ternary operator", like this?:

{{ value ?: defaultValue }}

instead of {{ value ? value : defaultValue }}

raw/verbatim tags

As noticed in #18

include tag with "with" and "only" modifiers

As noticed in #18

Whitespace control

As noticed in #18

Whitespace Control {% set foo = ' bar ' %}|{{- foo }}| return null instead of bar

spaceless tag

As noticed in #18

string interpolation

As noticed in #18

cache: false doesn't work

It seems that template parser doesn't check options.cache variable and always cache compiled templates

asyncronous tags

Is it possible to add support of asyncronous tags?
for example i want to create tag "render" (like in symfony) and use it in templates like:

{% render('top_10_news_controller') %}

but controller can't immediately return data for top 10 news (for example controller gets them from database)

template_from_string function

As noticed in #18

Non implemented Tags/Filters/Functions/Tests/Operators

This is just a list of things that are not implemented not an actual issue :)

Tags

• do
• embed
• filter (partially implemented)
• include does not support with and only options
• set {% set foo, bar = 'foo', 'bar' %} this method of assign is not supported
• spaceless
• use
• verbatim
• flush
• raw
• sandbox

Filters

• abs {% set number = -5 %}{{ number|abs }} this works but this: {{ -5|abs }} is not. same applies in Twig engine
• batch
• striptags
• split
• reverse with strings and numbers (works only with arrays)
• slice
• trim with special characters
• url_encode
• convert_encoding does not make sense in JavaScript
• date_modify
• merge
• number_format
• replace
• escape css, url and html_attr are not supported
• first
• last
• date

Functions

• constant does not make sense in JavaScript
• attribute
• template_from_string
• date
• dump with several arguments (only first is dumped)
• include
• random outputs 'null'

Tests

• constant does not make sense in JavaScript
• empty returns true only if the variable is undefined or null, should return true when null, false, an empty array, or the empty string.
• iterable works only with arrays should also work with iterable objects like { foo : 'Foo', bar : 'Bar'}
• null

Operators

• {{ 'cd' in 'abcde' }} returns false, should return true

Misc

• String interpolation is not working {{ "foo #{1 + 2} baz" }}
• Whitespace Control {% set foo = ' bar ' %}|{{- foo }}| return null instead of bar
• {% if 1 not in [1, 2, 3] %} throws exception but {% if not (1 in [1, 2, 3]) %} works fine

Fix parent() and block() functions

dump - limit depth

Sometimes objects are big and dump function provides very big output. Is it possible to add some function which can limit depth of dumping (like 3rd option in util.inspect)?

maybe alias for util.inspect like.
{{ inspect(var, false, 3) }}
There is only problem with colorizing

date_modify filter

As noticed in #18, date_modify filter is not implemented.

Improve error reporting

Error reporting related to templates should be improved adding line numbers in order to track down the reported problem.

first and last filters

As noticed in #18

Implement "date" function

As noticed in #18.

Not implemented date function

http://twig.sensiolabs.org/doc/functions/date.html

include function

As noticed in #18

filter tag with multiple filters and parameters

As noticed in #18

Improve tree node generation

Currently the node generation is a mess. It mixes node generation with generating code to the output. It should generate just a node and then generate the code with that.

number_format filter

As noticed in #18

batch filter

As noticed in #18

slice filter doesn't work fine

With arrays it is using start+end instead of start+length.
Doesn't work with strings or numbers.

Implement additional escaping strategies

Currently only supports HTML escaping strategy.

attribute function

As noticed in #18

Refactorings, cleanups and documenting

set tag tuple assignments

As noticed in #18

Implementation without express/connect

An example of implementation without express/connect just stand-alone template engine would be helpful as well.

Thanks

reverse with strings and numbers (works only with arrays)

As noticed in #18

reverse with strings and numbers (works only with arrays)

add support for twig options

add support of options

autoescape
strict_variables

http://twig.sensiolabs.org/doc/api.html

embed tag

As noticed in #18

integer divide support

There is an operator to perform a truncate division: a // b

trim with special characters

As noticed in #18

Support in operator with strings

As noticed by panosru here #18 :

{{ 'cd' in 'abcde' }} returns false, should return true

merge filter

As noticed in #18

url_encode filter

As noticed in #18

Automatically detect abosule paths

I think atpl should automatically detects absolute file paths and not prepend them with root dir;

smth like this:

function isAbsolutePath (path) {
    if ('/' == path[0]) {
        return true;
    }
    if (':' == path[1] && '\\' == path[2]) {
        return true;
    }
    return false;
};

json_encode fails with "Converting circular structure to JSON"

I found an issue with json_encode (basically in JSON.stringify) - "Converting circular structure to JSON"
for example in

a = {};
b = {a: a};
a.b = b;

console.log(a) and console.log(util.inspect(a, false, null, false)) provides { b: { a: [Circular] } }, but JSON.stringify crashes with "Converting circular structure to JSON"

I think we should found a workaround in json_encode. Maybe some addition parameter to json_encode (like in JSON.stringify - depth and replacer). or option like 'prevent_circular'

striptags filter

As noticed in #18

"not in" operator doesn't work

As noticed in #18:

{% if 1 not in [1, 2, 3] %} throws exception but {% if not (1 in [1, 2, 3]) %} works fine

export render function

It would be nice to do smth like this:

atpl = require('atpl');

var engine = new atpl({cahe: false, root: ...});
engine.renderFile(filename, data, callback);

or

atpl = require('atpl');
atpl.renderFile(filename, {cache: false, root: ...}, data, callback);