ErlyDTL compiles Django Template Language to Erlang bytecode.
Project homepage: https://github.com/erlydtl/erlydtl/wiki
ErlyDTL implements the Django Template Language as documented for version 1.6, here: http://docs.djangoproject.com/en/1.6/ref/templates/builtins/
Despite our best efforts to be completely compatible with the Django Template Languge, there are still a few differences.
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:
-
outdir- 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
TagVarsare variables provided to a custom tag in the template's body (e.g.{% foo bar=100 %}results inTagVars = [{bar, 100}]). TheOptionsare options passed as the second argument to therender/2call at render-time. (These may include any options, not justlocaleandtranslation_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. (Currently not strictly true, see #61) -
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 with extra options passed directly tocompiler:forms/2. This option can be supplied multiple times. Note that the most common options can be given directly with the list of options to the erlydtl compiler (see Erlang Compiler options, below). -
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 translatingblocktransblocks. This will be called once for each pair ofblocktransblock 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. -
record_info- List of records to look for when rendering the template. Each record info is a tuple with the fields of the record:{my_record, record_info(fields, my_record)} -
no_env- Do not read additional options from the OS environment variableERLYDTL_COMPILER_OPTIONS. -
no_load- Do not load the compiled template. -
binary- Include the compiled template binary code in the result tuple (between the module name and any warning/error lists). Note, this option is named the same as for the Erlang compiler, with similar use, except that this option does NOT affect whether or not a .beam file is saved.
Erlang Compiler options
As a convenience, the following options are forwarded to
compile:forms/2, along with those from compiler_options:
returnreturn_warningsreturn_errorsreportreport_warningsreport_errorswarnings_as_errorsverbose
Notice that the return value from erlydtl:compile is affected by
the options passed to the compiler. See
Erlang compiler documentation
for details. Exception to the rule is that we have reverted the
forms statement that binary is treated as implicitly set. That is,
you need to pass the binary option to erlydtl in order to get the
code in the result tuple.
Default compiler options are [verbose, report_errors], which gives
either a {ok, Module} or error as return value.
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_funcompile-time option.my_compiled_template:translatable_strings() -> [String]List of strings appearing in
{% trans %}tags that can be overridden with a dictionary passed torender/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 providedblocktrans_extractormodule.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.
csrf_tokenThe Cross Site Request Forgery tag is not implemented.urlThe url tag is not implemented. This should be addressed in a future release.regrouprequires a closingendregrouptag. See Issue #101.
From a Unix shell, run:
make test
Note that the tests will create some output in tests/output.
