Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 187 lines (114 sloc) 6.809 kb
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
1 ErlyDTL
2 =======
3
9646b5a @evanmiller Implement "iriencode" filter
evanmiller authored
4 ErlyDTL compiles Django Template Language to Erlang bytecode.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
5
c624a50 Support for {% regroup %} tag.
Evan Miller authored
6 *Supported tags*: autoescape, block, blocktrans, comment, cycle, extends, filter, firstof, for, if, ifchanged, ifequal, ifnotequal, include, now, regroup, spaceless, ssi, templatetag, trans, widthratio, with
00165a6 @evanmiller Indicate which tags are still unsupported
evanmiller authored
7
c624a50 Support for {% regroup %} tag.
Evan Miller authored
8 _Unsupported tags_: csrf_token, url
00165a6 @evanmiller Indicate which tags are still unsupported
evanmiller authored
9
74706d8 @nyaray Implemented and documented truncatechars from django dev.
nyaray authored
10 *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
00165a6 @evanmiller Indicate which tags are still unsupported
evanmiller authored
11
9646b5a @evanmiller Implement "iriencode" filter
evanmiller authored
12 _Unsupported filters_: _none_
00165a6 @evanmiller Indicate which tags are still unsupported
evanmiller authored
13
6ec04c4 @evanmiller Make README look nice on GitHub
evanmiller authored
14 Project homepage: <http://code.google.com/p/erlydtl/>
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
15
ccbfa71 @evanmiller Update README
evanmiller authored
16 Language reference: <http://docs.djangoproject.com/en/dev/ref/templates/builtins/>
17
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
18
19 Compilation
20 -----------
21
25480ec @evanmiller More formatting
evanmiller authored
22 To compile ErlyDTL, run
23
24 make
25
26 in this directory.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
27
28
29 Template compilation
30 --------------------
31
32 Four ways:
33
34 erlydtl:compile("/path/to/template.dtl", my_module_name)
35
36 erlydtl:compile("/path/to/template.dtl", my_module_name, Options)
37
38 erlydtl:compile(<<"<html>{{ foo }}</html>">>, my_module_name)
39
40 erlydtl:compile(<<"<html>{{ foo }}</html>">>, my_module_name, Options)
41
42 Options is a proplist possibly containing:
43
ad54ffc @evanmiller More formatting
evanmiller authored
44 * `out_dir` - Directory to store generated .beam files. If not specified, no
45 .beam files will be created.
0d99ae2 @evanmiller * Change: No .beam file will be generated unless out_dir is specified.
evanmiller authored
46
ad54ffc @evanmiller More formatting
evanmiller authored
47 * `doc_root` - Included template paths will be relative to this directory;
48 defaults to the compiled template's directory.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
49
ad54ffc @evanmiller More formatting
evanmiller authored
50 * `custom_tags_dir` - Directory of DTL files (no extension) includable as tags.
6c59be1 @evanmiller Compile custom tags at most once per template
evanmiller authored
51 E.g. if $custom_tags_dir/foo contains `<b>{{ bar }}</b>`, then `{% foo bar=100 %}`
ad54ffc @evanmiller More formatting
evanmiller authored
52 will evaluate to `<b>100</b>`. Get it?
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
53
8384b6d custom_tags_modules (plural) and reqd applications
Evan Miller authored
54 * `custom_tags_modules` - A list of modules to be used for handling custom
55 tags. The modules will be searched in order and take precedence over
56 `custom_tags_dir`. Each custom tag should correspond to an exported function,
57 e.g.:
d4aa8a1 @evanmiller Support for custom tags modules
evanmiller authored
58
8384b6d custom_tags_modules (plural) and reqd applications
Evan Miller authored
59 some_tag(Variables, Context) -> iolist()
60
61 The `Context` is specified at render-time with the `custom_tags_context` option.
d4aa8a1 @evanmiller Support for custom tags modules
evanmiller authored
62
b076a6e New compile-time option: custom_filters_modules
Evan Miller authored
63 * `custom_filters_modules` - A list of modules to be used for handling custom
64 filters. The modules will be searched in order and take precedence over the
65 built-in filters. Each custom filter should correspond to an exported filter,
66 e.g.
67
68 some_filter(Value) -> iolist()
69
70 If the filter takes an argument (e.g. "foo:2"), the argument will be also be
71 passed in:
72
73 some_filter(Value, Arg) -> iolist()
74
ad54ffc @evanmiller More formatting
evanmiller authored
75 * `vars` - Variables (and their values) to evaluate at compile-time rather than
76 render-time.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
77
ad54ffc @evanmiller More formatting
evanmiller authored
78 * `reader` - {module, function} tuple that takes a path to a template and returns
373ba28 @evanmiller More formatting
evanmiller authored
79 a binary with the file contents. Defaults to `{file, read_file}`. Useful
ad54ffc @evanmiller More formatting
evanmiller authored
80 for reading templates from a network resource.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
81
373ba28 @evanmiller More formatting
evanmiller authored
82 * `compiler_options` - Proplist passed directly to `compiler:forms/2`
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
83
ad54ffc @evanmiller More formatting
evanmiller authored
84 * `force_recompile` - Recompile the module even if the source's checksum has not
85 changed. Useful for debugging.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
86
ad54ffc @evanmiller More formatting
evanmiller authored
87 * `locale` - The locale used for template compile. Requires erlang_gettext. It
373ba28 @evanmiller More formatting
evanmiller authored
88 will ask gettext_server for the string value on the provided locale.
89 For example, adding {locale, "en_US"} will call {key2str, Key, "en_US"}
90 for all string marked as trans (`{% trans "StringValue" %}` on templates).
91 See README_I18N.
48fea22 Implement "trans" tag with support for .po files
Evan Miller authored
92
694fc92 Preliminary blocktrans support
Evan Miller authored
93 * `blocktrans_fun` - A two-argument fun to use for translating `blocktrans`
94 blocks. This will be called once for each pair of `blocktrans` block and locale
95 specified in `blocktrans_locales`. The fun should take the form:
96
dc377d7 {% blocktrans %} no longer uses identifiers
Evan Miller authored
97 Fun(Block::string(), Locale::string()) -> <<"ErlyDTL code">> | default
694fc92 Preliminary blocktrans support
Evan Miller authored
98
99 * `blocktrans_locales` - A list of locales to be passed to `blocktrans_fun`.
100 Defaults to [].
101
c17a770 Compile to binaries by default
Evan Miller authored
102 * `binary_strings` - Whether to compile strings as binary terms (rather than
103 lists). Defaults to `true`.
104
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
105
d4aa8a1 @evanmiller Support for custom tags modules
evanmiller authored
106 Helper compilation
107 ------------------
108
109 Helpers provide additional templating functionality and can be used in
110 conjunction with the `custom_tags_module` option above. They can be created
111 from a directory of templates thusly:
112
113 erlydtl:compile_dir("/path/to/dir", my_helper_module_name)
114
115 erlydtl:compile_dir("/path/to/dir", my_helper_module_name, Options)
116
117 The resulting module will export a function for each template appearing
118 in the specified directory. Options is the same as for compile/3.
119
120 Compiling a helper module can be more efficient than using `custom_tags_dir`
121 because the helper functions will be compiled only once (rather than once
122 per template).
123
124
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
125 Usage (of a compiled template)
126 ------------------------------
127
128 my_compiled_template:render(Variables) -> {ok, IOList} | {error, Err}
129
6ec04c4 @evanmiller Make README look nice on GitHub
evanmiller authored
130 Variables is a proplist, dict, gb_tree, or a parameterized module
131 (whose method names correspond to variable names). The variable
132 values can be atoms, strings, binaries, or (nested) variables.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
133
6ec04c4 @evanmiller Make README look nice on GitHub
evanmiller authored
134 IOList is the rendered template.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
135
694fc92 Preliminary blocktrans support
Evan Miller authored
136 my_compiled_template:render(Variables, Options) ->
550bbe4 @evanmiller Support for i18n at run-time.
evanmiller authored
137 {ok, IOList} | {error, Err}
138
694fc92 Preliminary blocktrans support
Evan Miller authored
139 Same as `render/1`, but with the following options:
140
141 * `translation_fun` - A fun/1 that will be used to translate strings appearing
142 inside `{% trans %}` tags. The simplest TranslationFun would be `fun(Val) ->
143 Val end`
144
145 * `locale` - A string specifying the current locale, for use with the
146 `blocktrans_fun` compile-time option.
550bbe4 @evanmiller Support for i18n at run-time.
evanmiller authored
147
8384b6d custom_tags_modules (plural) and reqd applications
Evan Miller authored
148 * `custom_tags_context` - A value that will be passed to custom tags.
149
550bbe4 @evanmiller Support for i18n at run-time.
evanmiller authored
150 my_compiled_template:translatable_strings() -> [String]
151
dc377d7 {% blocktrans %} no longer uses identifiers
Evan Miller authored
152 List of strings appearing in `{% trans %}` tags that can be overridden with
153 a dictionary passed to `render/2`.
154
155 my_compiled_template:translated_blocks() -> [String]
156
157 List of strings appearing in `{% blocktrans %}...{% endblocktrans %}` blocks;
158 the translations (which can contain ErlyDTL code) are hard-coded into the
159 module and appear at render-time. To get a list of translatable blocks before
160 compile-time, use the provided `blocktrans_extractor` module.
550bbe4 @evanmiller Support for i18n at run-time.
evanmiller authored
161
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
162 my_compiled_template:source() -> {FileName, CheckSum}
163
6ec04c4 @evanmiller Make README look nice on GitHub
evanmiller authored
164 Name and checksum of the original template file.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
165
166 my_compiled_template:dependencies() -> [{FileName, CheckSum}]
167
6ec04c4 @evanmiller Make README look nice on GitHub
evanmiller authored
168 List of names/checksums of templates included by the original template
169 file. Useful for frameworks that recompile a template only when the
170 template's dependencies change.
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
171
172
c624a50 Support for {% regroup %} tag.
Evan Miller authored
173 Differences from standard Django Template Language
174 --------------------------------------------------
175
176 The "regroup" tag must have an ending "endregroup" tag.
177
178
7a2813e @evanmiller * Run functional tests from "make test"
evanmiller authored
179 Tests
180 -----
181
182 From a Unix shell, run:
183
184 make test
185
ae6bf4b @evanmiller Integrate new filters and tests from dgulino
evanmiller authored
186 Note that the tests will create some output in tests/output.
Something went wrong with that request. Please try again.