ErlyDTL compiles Django Template Language to Erlang bytecode.
Supported tags: autoescape, block, blocktrans, comment, cycle, extends, filter, firstof, for, if, ifchanged, ifequal, ifnotequal, include, now, regroup, spaceless, ssi, templatetag, trans, verbatim, widthratio, with
Unsupported tags: csrf_token, url
Supported filters: add, addslashes, capfirst, center, cut, date, default, default_if_none, dictsort, dictsortreversed, divisibleby, escape, escapejs, filesizeformat, first, fix_ampersands, floatformat, force_escape, format_integer, format_number, get_digit, iriencode, join, last, length, length_is, linebreaks, linebreaksbr, linenumbers, ljust, lower, make_list, phonenumeric, pluralize, pprint, random, random_num, random_range, removetags, rjust, safe, safeseq, slice, slugify, stringformat, striptags, time, timesince, timeuntil, title, truncatechars, truncatewords, truncatewords_html, unordered_list, upper, urlencode, urlize, urlizetrunc, wordcount, wordwrap, yesno
Unsupported filters: none
Project homepage: http://code.google.com/p/erlydtl/
Language reference: http://docs.djangoproject.com/en/dev/ref/templates/builtins/
To compile ErlyDTL, run
make
in this directory.
Four ways:
erlydtl:compile("/path/to/template.dtl", my_module_name)
erlydtl:compile("/path/to/template.dtl", my_module_name, Options)
erlydtl:compile(<<"<html>{{ foo }}</html>">>, my_module_name)
erlydtl:compile(<<"<html>{{ foo }}</html>">>, my_module_name, Options)
Options is a proplist possibly containing:
-
out_dir
- Directory to store generated .beam files. If not specified, no .beam files will be created. -
doc_root
- Included template paths will be relative to this directory; defaults to the compiled template's directory. -
custom_tags_dir
- Directory of DTL files (no extension) includable as tags. E.g. if $custom_tags_dir/foo contains<b>{{ bar }}</b>
, then{% foo bar=100 %}
will evaluate to<b>100</b>
. Get it? -
custom_tags_modules
- A list of modules to be used for handling custom tags. The modules will be searched in order and take precedence overcustom_tags_dir
. Each custom tag should correspond to an exported function with one of the following signatures:some_tag(TagVars) -> iolist() some_tag(TagVars, Options) -> iolist()
The TagVars
are variables provided to a custom tag in the template's body
(e.g. {% foo bar=100 %}
results in TagVars = [{bar, 100}]
).
The Options
are options passed as the second argument to the render/2
call
at render-time. (These may include any options, not just locale
and
translation_fun
.)
-
custom_filters_modules
- A list of modules to be used for handling custom filters. The modules will be searched in order and take precedence over the built-in filters. Each custom filter should correspond to an exported filter, e.g.some_filter(Value) -> iolist()
If the filter takes an argument (e.g. "foo:2"), the argument will be also be passed in:
some_filter(Value, Arg) -> iolist()
-
vars
- Variables (and their values) to evaluate at compile-time rather than render-time. -
reader
- {module, function} tuple that takes a path to a template and returns a binary with the file contents. Defaults to{file, read_file}
. Useful for reading templates from a network resource. -
compiler_options
- Proplist passed directly tocompiler:forms/2
-
force_recompile
- Recompile the module even if the source's checksum has not changed. Useful for debugging. -
locale
- The locale used for template compile. Requires erlang_gettext. It will ask gettext_server for the string value on the provided locale. For example, adding {locale, "en_US"} will call {key2str, Key, "en_US"} for all string marked as trans ({% trans "StringValue" %}
on templates). See README_I18N. -
blocktrans_fun
- A two-argument fun to use for translatingblocktrans
blocks. This will be called once for each pair ofblocktrans
block and locale specified inblocktrans_locales
. The fun should take the form:Fun(Block::string(), Locale::string()) -> <<"ErlyDTL code">> | default
-
blocktrans_locales
- A list of locales to be passed toblocktrans_fun
. Defaults to []. -
binary_strings
- Whether to compile strings as binary terms (rather than lists). Defaults totrue
. -
verbose
- Enable verbose printing of compilation results.
Additional compiler options can be provided with the ERLYDTL_COMPILER_OPTIONS
OS environment variable.
Helpers provide additional templating functionality and can be used in
conjunction with the custom_tags_module
option above. They can be created
from a directory of templates thusly:
erlydtl:compile_dir("/path/to/dir", my_helper_module_name)
erlydtl:compile_dir("/path/to/dir", my_helper_module_name, Options)
The resulting module will export a function for each template appearing in the specified directory. Options is the same as for compile/3.
Compiling a helper module can be more efficient than using custom_tags_dir
because the helper functions will be compiled only once (rather than once
per template).
my_compiled_template:render(Variables) -> {ok, IOList} | {error, Err}
Variables is a proplist, dict, gb_tree, or a parameterized module (whose method names correspond to variable names). The variable values can be atoms, strings, binaries, or (nested) variables.
IOList is the rendered template.
my_compiled_template:render(Variables, Options) ->
{ok, IOList} | {error, Err}
Same as render/1
, but with the following options:
-
translation_fun
- A fun/1 that will be used to translate strings appearing inside{% trans %}
tags. The simplest TranslationFun would befun(Val) -> Val end
-
locale
- A string specifying the current locale, for use with theblocktrans_fun
compile-time option.my_compiled_template:translatable_strings() -> [String]
List of strings appearing in {% trans %}
tags that can be overridden with
a dictionary passed to render/2
.
my_compiled_template:translated_blocks() -> [String]
List of strings appearing in {% blocktrans %}...{% endblocktrans %}
blocks;
the translations (which can contain ErlyDTL code) are hard-coded into the
module and appear at render-time. To get a list of translatable blocks before
compile-time, use the provided blocktrans_extractor
module.
my_compiled_template:source() -> {FileName, CheckSum}
Name and checksum of the original template file.
my_compiled_template:dependencies() -> [{FileName, CheckSum}]
List of names/checksums of templates included by the original template file. Useful for frameworks that recompile a template only when the template's dependencies change.
my_compiled_template:variables() -> [Variable::atom()]
Sorted list of unique variables used in the template's body. The list can be used for determining which variable bindings need to be passed to the render/3 function.
The "regroup" tag must have an ending "endregroup" tag.
From a Unix shell, run:
make test
Note that the tests will create some output in tests/output.