|
|
@@ -29,47 +29,79 @@ Template compilation
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
- erlydtl:compile_file("/path/to/template.dtl", my_module_name)
|
|
|
+```erlang
|
|
|
+erlydtl:compile_file("/path/to/template.dtl", my_module_name)
|
|
|
|
|
|
- erlydtl:compile_file("/path/to/template.dtl", my_module_name, Options)
|
|
|
+erlydtl:compile_file("/path/to/template.dtl", my_module_name, Options)
|
|
|
|
|
|
- erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name)
|
|
|
+erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name)
|
|
|
|
|
|
- erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name, Options)
|
|
|
+erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name, Options)
|
|
|
+```
|
|
|
|
|
|
Result:
|
|
|
|
|
|
- ok %% existing compiled template is up to date.
|
|
|
+```erlang
|
|
|
+ok %% existing compiled template is up to date.
|
|
|
|
|
|
- {ok, Module}
|
|
|
- {ok, Module, Warnings}
|
|
|
- {ok, Module, Binary}
|
|
|
- {ok, Module, Binary, Warnings}
|
|
|
+{ok, Module}
|
|
|
+{ok, Module, Warnings}
|
|
|
+{ok, Module, Binary}
|
|
|
+{ok, Module, Binary, Warnings}
|
|
|
|
|
|
- error
|
|
|
- {error, Errors, Warnings}
|
|
|
+error
|
|
|
+{error, Errors, Warnings}
|
|
|
+```
|
|
|
|
|
|
Options is a proplist possibly containing:
|
|
|
|
|
|
-* `out_dir` - Directory to store generated .beam files. If not
|
|
|
- specified, no .beam files will be created and a warning is
|
|
|
- emitted. To silence the warning, use `{out_dir, false}`.
|
|
|
+* `auto_escape` - Control automatic HTML escaping of template
|
|
|
+ values. Enabled by default.
|
|
|
|
|
|
-* `doc_root` - Included template paths will be relative to this
|
|
|
- directory; defaults to the compiled template's directory.
|
|
|
+* `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.
|
|
|
|
|
|
-* `libraries` - A list of `{Name, Module}` libraries implementing
|
|
|
- custom tags and filters. `Module` should implement the
|
|
|
- `erlydtl_library` behaviour.
|
|
|
+* `binary_strings` - Whether to compile strings as binary terms
|
|
|
+ (rather than lists). Defaults to `true`.
|
|
|
|
|
|
-* `default_libraries` - A list of libraries that should be loaded by
|
|
|
- default when compiling a template. Libraries can be specified either
|
|
|
- by name (when there is a name to module mapping also provided in the
|
|
|
- `libraries` option) or by module.
|
|
|
+* `blocktrans_fun` - A two-argument fun to use for translating
|
|
|
+ `blocktrans` blocks, `trans` tags and `_(..)` expressions. This will
|
|
|
+ be called once for each pair of translated element and locale
|
|
|
+ specified in `blocktrans_locales`. The fun should take the form:
|
|
|
+
|
|
|
+ ```erlang
|
|
|
+ Fun(Block::string(), Locale::string()) -> <<"ErlyDTL code">>::binary() | default
|
|
|
+ ```
|
|
|
+
|
|
|
+* `blocktrans_locales` - A list of locales to be passed to
|
|
|
+ `blocktrans_fun`. Defaults to [].
|
|
|
+
|
|
|
+* `compiler_options` - Proplist with extra options passed directly to
|
|
|
+ `compiler:forms/2`. This can prove useful when using extensions to
|
|
|
+ add extra defines etc when compiling the generated code.
|
|
|
+
|
|
|
+* `custom_filters_modules` **deprecated** - 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.
|
|
|
+
|
|
|
+ ```erlang
|
|
|
+ some_filter(Value) -> iolist()
|
|
|
+ ```
|
|
|
+
|
|
|
+ If the filter takes any arguments (e.g. "foo:2"), those will be
|
|
|
+ added to the call:
|
|
|
+
|
|
|
+ ```erlang
|
|
|
+ some_filter(Value, Arg) -> iolist()
|
|
|
+ ```
|
|
|
|
|
|
* `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>`.
|
|
|
+ as tags. E.g. if `$custom_tags_dir/foo` contains `<b>{{ bar
|
|
|
+ }}</b>`, then `{% foo bar=100 %}` will evaluate to `<b>100</b>`.
|
|
|
|
|
|
* `custom_tags_modules` **deprecated** - A list of modules to be used
|
|
|
for handling custom tags. The modules will be searched in order and
|
|
|
@@ -77,8 +109,10 @@ Options is a proplist possibly containing:
|
|
|
correspond to an exported function with one of the following
|
|
|
signatures:
|
|
|
|
|
|
- some_tag(TagVars) -> iolist()
|
|
|
- some_tag(TagVars, Options) -> iolist()
|
|
|
+ ```erlang
|
|
|
+ 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 =
|
|
|
@@ -86,62 +120,51 @@ Options is a proplist possibly containing:
|
|
|
argument to the `render/2` call at render-time. (These may include
|
|
|
any options, not just `locale` and `translation_fun`.)
|
|
|
|
|
|
-* `custom_filters_modules` **deprecated** - 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()
|
|
|
+* `debug_info` - This option is passed to `compile:forms` to include
|
|
|
+ debug information in the compiled module. It will also print all
|
|
|
+ options passed to `compile:forms` if verbosity is >= 2 (e.g. with
|
|
|
+ two or more `verbose` options) and save the compiled template in
|
|
|
+ source form to a .erl file.
|
|
|
|
|
|
- If the filter takes any arguments (e.g. "foo:2"), those will be
|
|
|
- added to the call:
|
|
|
+* `default_libraries` - A list of libraries that should be loaded by
|
|
|
+ default when compiling a template. Libraries can be specified either
|
|
|
+ by name (when there is a name to module mapping also provided in the
|
|
|
+ `libraries` option) or by module.
|
|
|
|
|
|
- some_filter(Value, Arg) -> iolist()
|
|
|
+* `doc_root` - Included template paths will be relative to this
|
|
|
+ directory; defaults to the compiled template's directory.
|
|
|
|
|
|
-* `vars` - Variables (and their values) to evaluate at compile-time
|
|
|
- rather than render-time. (Currently not strictly true, see
|
|
|
- [#61](https://github.com/erlydtl/erlydtl/issues/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.
|
|
|
+* `extension_module` **experimental** - This is work in progress to
|
|
|
+ make erlydtl extensible.
|
|
|
|
|
|
* `force_recompile` - Recompile the module even if the source's
|
|
|
checksum has not changed. Useful for debugging.
|
|
|
|
|
|
-* `locale` - DEPRECATED. The same as {blocktrans_locales, [Val]}.
|
|
|
+* `libraries` - A list of `{Name, Module}` libraries implementing
|
|
|
+ custom tags and filters. `Module` should implement the
|
|
|
+ `erlydtl_library` behaviour.
|
|
|
|
|
|
-* `blocktrans_fun` - A two-argument fun to use for translating
|
|
|
- `blocktrans` blocks, `trans` tags and `_(..)` expressions. This will
|
|
|
- be called once for each pair of translated element and locale
|
|
|
- specified in `blocktrans_locales`. The fun should take the form:
|
|
|
+* `locale` **deprecated** - The same as {blocktrans_locales, [Val]}.
|
|
|
|
|
|
- Fun(Block::string(), Locale::string()) -> <<"ErlyDTL code">>::binary() | default
|
|
|
+* `no_env` - Do not read additional options from the OS environment
|
|
|
+ variable `ERLYDTL_COMPILER_OPTIONS`.
|
|
|
|
|
|
-* `blocktrans_locales` - A list of locales to be passed to
|
|
|
- `blocktrans_fun`. Defaults to [].
|
|
|
+* `no_load` - Do not load the compiled template.
|
|
|
|
|
|
-* `binary_strings` - Whether to compile strings as binary terms
|
|
|
- (rather than lists). Defaults to `true`.
|
|
|
+* `out_dir` - Directory to store generated .beam files. If not
|
|
|
+ specified, no .beam files will be created and a warning is
|
|
|
+ emitted. To silence the warning, use `{out_dir, false}`.
|
|
|
+
|
|
|
+* `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.
|
|
|
|
|
|
* `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
|
|
|
- variable `ERLYDTL_COMPILER_OPTIONS`.
|
|
|
-
|
|
|
-* `auto_escape` - Control automatic HTML escaping of template
|
|
|
- values. Enabled by default.
|
|
|
-
|
|
|
-* `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
|
|
|
+ {my_record, record_info(fields, my_record)}
|
|
|
+ ```
|
|
|
|
|
|
* `return` - Short form for both `return_warnings` and `return_errors`.
|
|
|
|
|
|
@@ -158,13 +181,14 @@ Options is a proplist possibly containing:
|
|
|
|
|
|
* `report_errors` - Print errors as they occur.
|
|
|
|
|
|
-* `warnings_as_errors` - Treat warnings as errors.
|
|
|
+* `vars` - Variables (and their values) to evaluate at compile-time
|
|
|
+ rather than render-time. (Currently not strictly true, see
|
|
|
+ [#61](https://github.com/erlydtl/erlydtl/issues/61))
|
|
|
|
|
|
-* `verbose` - Enable verbose printing of compilation results.
|
|
|
+* `verbose` - Enable verbose printing of compilation progress. Add
|
|
|
+ several for even more verbose (e.g. debug) output.
|
|
|
|
|
|
-* `compiler_options` - Proplist with extra options passed directly to
|
|
|
- `compiler:forms/2`. This can prove useful when using extensions to
|
|
|
- add extra defines etc when compiling the generated code.
|
|
|
+* `warnings_as_errors` - Treat warnings as errors.
|
|
|
|
|
|
|
|
|
Helper compilation
|
|
|
@@ -174,9 +198,11 @@ 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)
|
|
|
+```erlang
|
|
|
+erlydtl:compile_dir("/path/to/dir", my_helper_module_name)
|
|
|
|
|
|
- erlydtl:compile_dir("/path/to/dir", my_helper_module_name, Options)
|
|
|
+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
|
|
|
@@ -190,7 +216,10 @@ once (rather than once per template).
|
|
|
Usage (of a compiled template)
|
|
|
------------------------------
|
|
|
|
|
|
- my_compiled_template:render(Variables) -> {ok, IOList} | {error, Err}
|
|
|
+
|
|
|
+```erlang
|
|
|
+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
|
|
|
@@ -198,26 +227,33 @@ can be atoms, strings, binaries, or (nested) variables.
|
|
|
|
|
|
IOList is the rendered template.
|
|
|
|
|
|
- my_compiled_template:render(Variables, Options) ->
|
|
|
- {ok, IOList} | {error, Err}
|
|
|
+
|
|
|
+```erlang
|
|
|
+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 %}` and `{% blocktrans %}` tags. The simplest
|
|
|
- TranslationFun would be `fun(Val) -> Val end`. Placeholders for
|
|
|
- blocktrans variable interpolation should be wrapped to `{{` and `}}`.
|
|
|
+ appearing inside `{% trans %}` and `{% blocktrans %}` tags. The
|
|
|
+ simplest TranslationFun would be `fun(Val) -> Val end`. Placeholders
|
|
|
+ for blocktrans variable interpolation should be wrapped to `{{` and
|
|
|
+ `}}`.
|
|
|
|
|
|
* `locale` - A string specifying the current locale, for use with the
|
|
|
`blocktrans_fun` compile-time option.
|
|
|
|
|
|
+
|
|
|
```erlang
|
|
|
my_compiled_template:translatable_strings() -> [String]
|
|
|
```
|
|
|
|
|
|
List of strings appearing in `{% trans %}` and `_(..)` tags.
|
|
|
|
|
|
- my_compiled_template:translated_blocks() -> [String]
|
|
|
+
|
|
|
+```erlang
|
|
|
+my_compiled_template:translated_blocks() -> [String]
|
|
|
+```
|
|
|
|
|
|
List of strings appearing in `{% blocktrans %}...{% endblocktrans %}`
|
|
|
blocks; the translations (which can contain ErlyDTL code) are
|
|
|
@@ -225,17 +261,26 @@ 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}
|
|
|
+
|
|
|
+```erlang
|
|
|
+my_compiled_template:source() -> {FileName, CheckSum}
|
|
|
+```
|
|
|
|
|
|
Name and checksum of the original template file.
|
|
|
|
|
|
- my_compiled_template:dependencies() -> [{FileName, CheckSum}]
|
|
|
+
|
|
|
+```erlang
|
|
|
+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()]
|
|
|
+
|
|
|
+```erlang
|
|
|
+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
|
Andreas Stenius