Mercurial > genshi > mirror
comparison doc/text-templates.txt @ 820:9755836bb396 experimental-inline
Sync (old) experimental inline branch with trunk@1027.
author | cmlenz |
---|---|
date | Wed, 11 Mar 2009 17:51:06 +0000 |
parents | 3eb30e4ece8c |
children |
comparison
equal
deleted
inserted
replaced
500:3eb30e4ece8c | 820:9755836bb396 |
---|---|
4 Genshi Text Template Language | 4 Genshi Text Template Language |
5 ============================= | 5 ============================= |
6 | 6 |
7 In addition to the XML-based template language, Genshi provides a simple | 7 In addition to the XML-based template language, Genshi provides a simple |
8 text-based template language, intended for basic plain text generation needs. | 8 text-based template language, intended for basic plain text generation needs. |
9 The language is similar to Cheetah_ or Velocity_. | 9 The language is similar to the Django_ template language. |
10 | |
11 .. _cheetah: http://cheetahtemplate.org/ | |
12 .. _velocity: http://jakarta.apache.org/velocity/ | |
13 | 10 |
14 This document describes the template language and will be most useful as | 11 This document describes the template language and will be most useful as |
15 reference to those developing Genshi text templates. Templates are text files of | 12 reference to those developing Genshi text templates. Templates are text files of |
16 some kind that include processing directives_ that affect how the template is | 13 some kind that include processing directives_ that affect how the template is |
17 rendered, and template expressions that are dynamically substituted by | 14 rendered, and template expressions that are dynamically substituted by |
18 variable data. | 15 variable data. |
19 | 16 |
20 See `Genshi Templating Basics <templates.html>`_ for general information on | 17 See `Genshi Templating Basics <templates.html>`_ for general information on |
21 embedding Python code in templates. | 18 embedding Python code in templates. |
22 | 19 |
20 .. note:: Actually, Genshi currently has two different syntaxes for text | |
21 templates languages: One implemented by the class ``OldTextTemplate`` | |
22 and another implemented by ``NewTextTemplate``. This documentation | |
23 concentrates on the latter, which is planned to completely replace the | |
24 older syntax. The older syntax is briefly described under legacy_. | |
25 | |
26 .. _django: http://www.djangoproject.com/ | |
23 | 27 |
24 .. contents:: Contents | 28 .. contents:: Contents |
25 :depth: 3 | 29 :depth: 3 |
26 .. sectnum:: | 30 .. sectnum:: |
27 | 31 |
30 | 34 |
31 ------------------- | 35 ------------------- |
32 Template Directives | 36 Template Directives |
33 ------------------- | 37 ------------------- |
34 | 38 |
35 Directives are lines starting with a ``#`` character followed immediately by | 39 Directives are template commands enclosed by ``{% ... %}`` characters. They can |
36 the directive name. They can affect how the template is rendered in a number of | 40 affect how the template is rendered in a number of ways: Genshi provides |
37 ways: Genshi provides directives for conditionals and looping, among others. | 41 directives for conditionals and looping, among others. |
38 | 42 |
39 Directives must be on separate lines, and the ``#`` character must be be the | 43 Each directive must be terminated using an ``{% end %}`` marker. You can add |
40 first non-whitespace character on that line. Each directive must be “closed” | 44 a string inside the ``{% end %}`` marker, for example to document which |
41 using a ``#end`` marker. You can add after the ``#end`` marker, for example to | 45 directive is being closed, or even the expression associated with that |
42 document which directive is being closed, or even the expression associated with | 46 directive. Any text after ``end`` inside the delimiters is ignored, and |
43 that directive. Any text after ``#end`` (but on the same line) is ignored, | 47 effectively treated as a comment. |
44 and effectively treated as a comment. | 48 |
45 | 49 If you want to include a literal delimiter in the output, you need to escape it |
46 If you want to include a literal ``#`` in the output, you need to escape it | 50 by prepending a backslash character (``\``). |
47 by prepending a backslash character (``\``). Note that this is **not** required | |
48 if the ``#`` isn't immediately followed by a letter, or it isn't the first | |
49 non-whitespace character on the line. | |
50 | 51 |
51 | 52 |
52 Conditional Sections | 53 Conditional Sections |
53 ==================== | 54 ==================== |
54 | 55 |
55 .. _`#if`: | 56 .. _`if`: |
56 | 57 |
57 ``#if`` | 58 ``{% if %}`` |
58 --------- | 59 ------------ |
59 | 60 |
60 The content is only rendered if the expression evaluates to a truth value:: | 61 The content is only rendered if the expression evaluates to a truth value: |
61 | 62 |
62 #if foo | 63 .. code-block:: genshitext |
64 | |
65 {% if foo %} | |
63 ${bar} | 66 ${bar} |
64 #end | 67 {% end %} |
65 | 68 |
66 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this | 69 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
67 would produce:: | 70 would produce:: |
68 | 71 |
69 Hello | 72 Hello |
70 | 73 |
71 | 74 |
72 .. _`#choose`: | 75 .. _`choose`: |
73 .. _`#when`: | 76 .. _`when`: |
74 .. _`#otherwise`: | 77 .. _`otherwise`: |
75 | 78 |
76 ``#choose`` | 79 ``{% choose %}`` |
77 ------------- | 80 ---------------- |
78 | 81 |
79 The ``#choose`` directive, in combination with the directives ``#when`` and | 82 The ``choose`` directive, in combination with the directives ``when`` and |
80 ``#otherwise`` provides advanced contional processing for rendering one of | 83 ``otherwise``, provides advanced contional processing for rendering one of |
81 several alternatives. The first matching ``#when`` branch is rendered, or, if | 84 several alternatives. The first matching ``when`` branch is rendered, or, if |
82 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered. | 85 no ``when`` branch matches, the ``otherwise`` branch is be rendered. |
83 | 86 |
84 If the ``#choose`` directive has no argument the nested ``#when`` directives | 87 If the ``choose`` directive has no argument the nested ``when`` directives will |
85 will be tested for truth:: | 88 be tested for truth: |
89 | |
90 .. code-block:: genshitext | |
86 | 91 |
87 The answer is: | 92 The answer is: |
88 #choose | 93 {% choose %} |
89 #when 0 == 1 | 94 {% when 0 == 1 %}0{% end %} |
90 0 | 95 {% when 1 == 1 %}1{% end %} |
91 #end | 96 {% otherwise %}2{% end %} |
92 #when 1 == 1 | 97 {% end %} |
93 1 | 98 |
94 #end | 99 This would produce the following output:: |
95 #otherwise | 100 |
96 2 | 101 The answer is: |
97 #end | 102 1 |
98 #end | 103 |
104 If the ``choose`` does have an argument, the nested ``when`` directives will | |
105 be tested for equality to the parent ``choose`` value: | |
106 | |
107 .. code-block:: genshitext | |
108 | |
109 The answer is: | |
110 {% choose 1 %}\ | |
111 {% when 0 %}0{% end %}\ | |
112 {% when 1 %}1{% end %}\ | |
113 {% otherwise %}2{% end %}\ | |
114 {% end %} | |
99 | 115 |
100 This would produce the following output:: | 116 This would produce the following output:: |
101 | 117 |
102 The answer is: | 118 The answer is: |
103 1 | 119 1 |
104 | 120 |
105 If the ``#choose`` does have an argument, the nested ``#when`` directives will | |
106 be tested for equality to the parent ``#choose`` value:: | |
107 | |
108 The answer is: | |
109 #choose 1 | |
110 #when 0 | |
111 0 | |
112 #end | |
113 #when 1 | |
114 1 | |
115 #end | |
116 #otherwise | |
117 2 | |
118 #end | |
119 #end | |
120 | |
121 This would produce the following output:: | |
122 | |
123 The answer is: | |
124 1 | |
125 | |
126 | 121 |
127 Looping | 122 Looping |
128 ======= | 123 ======= |
129 | 124 |
130 .. _`#for`: | 125 .. _`for`: |
131 | 126 |
132 ``#for`` | 127 ``{% for %}`` |
133 ---------- | 128 ------------- |
134 | 129 |
135 The content is repeated for every item in an iterable:: | 130 The content is repeated for every item in an iterable: |
131 | |
132 .. code-block:: genshitext | |
136 | 133 |
137 Your items: | 134 Your items: |
138 #for item in items | 135 {% for item in items %}\ |
139 * ${item} | 136 * ${item} |
140 #end | 137 {% end %} |
141 | 138 |
142 Given ``items=[1, 2, 3]`` in the context data, this would produce:: | 139 Given ``items=[1, 2, 3]`` in the context data, this would produce:: |
143 | 140 |
144 Your items | 141 Your items |
145 * 1 | 142 * 1 |
148 | 145 |
149 | 146 |
150 Snippet Reuse | 147 Snippet Reuse |
151 ============= | 148 ============= |
152 | 149 |
153 .. _`#def`: | 150 .. _`def`: |
154 .. _`macros`: | 151 .. _`macros`: |
155 | 152 |
156 ``#def`` | 153 ``{% def %}`` |
157 ---------- | 154 ------------- |
158 | 155 |
159 The ``#def`` directive can be used to create macros, i.e. snippets of template | 156 The ``def`` directive can be used to create macros, i.e. snippets of template |
160 text that have a name and optionally some parameters, and that can be inserted | 157 text that have a name and optionally some parameters, and that can be inserted |
161 in other places:: | 158 in other places: |
162 | 159 |
163 #def greeting(name) | 160 .. code-block:: genshitext |
161 | |
162 {% def greeting(name) %} | |
164 Hello, ${name}! | 163 Hello, ${name}! |
165 #end | 164 {% end %} |
166 ${greeting('world')} | 165 ${greeting('world')} |
167 ${greeting('everyone else')} | 166 ${greeting('everyone else')} |
168 | 167 |
169 The above would be rendered to:: | 168 The above would be rendered to:: |
170 | 169 |
171 Hello, world! | 170 Hello, world! |
172 Hello, everyone else! | 171 Hello, everyone else! |
173 | 172 |
174 If a macro doesn't require parameters, it can be defined as well as called | 173 If a macro doesn't require parameters, it can be defined without the |
175 without the parenthesis. For example:: | 174 parenthesis. For example: |
176 | 175 |
177 #def greeting | 176 .. code-block:: genshitext |
177 | |
178 {% def greeting %} | |
178 Hello, world! | 179 Hello, world! |
179 #end | 180 {% end %} |
180 ${greeting} | 181 ${greeting()} |
181 | 182 |
182 The above would be rendered to:: | 183 The above would be rendered to:: |
183 | 184 |
184 Hello, world! | 185 Hello, world! |
185 | 186 |
186 | 187 |
187 .. _includes: | 188 .. _includes: |
188 .. _`#include`: | 189 .. _`include`: |
189 | 190 |
190 ``#include`` | 191 ``{% include %}`` |
191 ------------ | 192 ----------------- |
192 | 193 |
193 To reuse common parts of template text across template files, you can include | 194 To reuse common parts of template text across template files, you can include |
194 other files using the ``#include`` directive:: | 195 other files using the ``include`` directive: |
195 | 196 |
196 #include "base.txt" | 197 .. code-block:: genshitext |
198 | |
199 {% include base.txt %} | |
197 | 200 |
198 Any content included this way is inserted into the generated output. The | 201 Any content included this way is inserted into the generated output. The |
199 included template sees the context data as it exists at the point of the | 202 included template sees the context data as it exists at the point of the |
200 include. `Macros`_ in the included template are also available to the including | 203 include. `Macros`_ in the included template are also available to the including |
201 template after the point it was included. | 204 template after the point it was included. |
204 processed. So if the example above was in the file "``myapp/mail.txt``" | 207 processed. So if the example above was in the file "``myapp/mail.txt``" |
205 (relative to the template search path), the include directive would look for | 208 (relative to the template search path), the include directive would look for |
206 the included file at "``myapp/base.txt``". You can also use Unix-style | 209 the included file at "``myapp/base.txt``". You can also use Unix-style |
207 relative paths, for example "``../base.txt``" to look in the parent directory. | 210 relative paths, for example "``../base.txt``" to look in the parent directory. |
208 | 211 |
209 Just like other directives, the argument to the ``#include`` directive accepts | 212 Just like other directives, the argument to the ``include`` directive accepts |
210 any Python expression, so the path to the included template can be determined | 213 any Python expression, so the path to the included template can be determined |
211 dynamically:: | 214 dynamically: |
212 | 215 |
213 #include '%s.txt' % filename | 216 .. code-block:: genshitext |
217 | |
218 {% include ${'%s.txt' % filename} %} | |
214 | 219 |
215 Note that a ``TemplateNotFound`` exception is raised if an included file can't | 220 Note that a ``TemplateNotFound`` exception is raised if an included file can't |
216 be found. | 221 be found. |
217 | 222 |
218 .. note:: The include directive for text templates was added in Genshi 0.5. | 223 .. note:: The include directive for text templates was added in Genshi 0.5. |
219 | 224 |
220 | 225 |
221 Variable Binding | 226 Variable Binding |
222 ================ | 227 ================ |
223 | 228 |
224 .. _`#with`: | 229 .. _`with`: |
225 | 230 |
226 ``#with`` | 231 ``{% with %}`` |
227 ----------- | 232 -------------- |
228 | 233 |
229 The ``#with`` directive lets you assign expressions to variables, which can | 234 The ``{% with %}`` directive lets you assign expressions to variables, which can |
230 be used to make expressions inside the directive less verbose and more | 235 be used to make expressions inside the directive less verbose and more |
231 efficient. For example, if you need use the expression ``author.posts`` more | 236 efficient. For example, if you need use the expression ``author.posts`` more |
232 than once, and that actually results in a database query, assigning the results | 237 than once, and that actually results in a database query, assigning the results |
233 to a variable using this directive would probably help. | 238 to a variable using this directive would probably help. |
234 | 239 |
235 For example:: | 240 For example: |
241 | |
242 .. code-block:: genshitext | |
236 | 243 |
237 Magic numbers! | 244 Magic numbers! |
238 #with y=7; z=x+10 | 245 {% with y=7; z=x+10 %} |
239 $x $y $z | 246 $x $y $z |
240 #end | 247 {% end %} |
241 | 248 |
242 Given ``x=42`` in the context data, this would produce:: | 249 Given ``x=42`` in the context data, this would produce:: |
243 | 250 |
244 Magic numbers! | 251 Magic numbers! |
245 42 7 52 | 252 42 7 52 |
246 | 253 |
247 Note that if a variable of the same name already existed outside of the scope | 254 Note that if a variable of the same name already existed outside of the scope |
248 of the ``#with`` directive, it will **not** be overwritten. Instead, it will | 255 of the ``with`` directive, it will **not** be overwritten. Instead, it will |
249 have the same value it had prior to the ``#with`` assignment. Effectively, | 256 have the same value it had prior to the ``with`` assignment. Effectively, |
250 this means that variables are immutable in Genshi. | 257 this means that variables are immutable in Genshi. |
258 | |
259 | |
260 .. _whitespace: | |
261 | |
262 --------------------------- | |
263 White-space and Line Breaks | |
264 --------------------------- | |
265 | |
266 Note that space or line breaks around directives is never automatically removed. | |
267 Consider the following example: | |
268 | |
269 .. code-block:: genshitext | |
270 | |
271 {% for item in items %} | |
272 {% if item.visible %} | |
273 ${item} | |
274 {% end %} | |
275 {% end %} | |
276 | |
277 This will result in two empty lines above and beneath every item, plus the | |
278 spaces used for indentation. If you want to supress a line break, simply end | |
279 the line with a backslash: | |
280 | |
281 .. code-block:: genshitext | |
282 | |
283 {% for item in items %}\ | |
284 {% if item.visible %}\ | |
285 ${item} | |
286 {% end %}\ | |
287 {% end %}\ | |
288 | |
289 Now there would be no empty lines between the items in the output. But you still | |
290 get the spaces used for indentation, and because the line breaks are removed, | |
291 they actually continue and add up between lines. There are numerous ways to | |
292 control white-space in the output while keeping the template readable, such as | |
293 moving the indentation into the delimiters, or moving the end delimiter on the | |
294 next line, and so on. | |
251 | 295 |
252 | 296 |
253 .. _comments: | 297 .. _comments: |
254 | 298 |
255 -------- | 299 -------- |
256 Comments | 300 Comments |
257 -------- | 301 -------- |
258 | 302 |
259 Lines where the first non-whitespace characters are ``##`` are removed from | 303 Parts in templates can be commented out using the delimiters ``{# ... #}``. |
260 the output, and can thus be used for comments. This can be escaped using a | 304 Any content in comments are removed from the output. |
305 | |
306 .. code-block:: genshitext | |
307 | |
308 {# This won't end up in the output #} | |
309 This will. | |
310 | |
311 Just like directive delimiters, these can be escaped by prefixing with a | |
261 backslash. | 312 backslash. |
313 | |
314 .. code-block:: genshitext | |
315 | |
316 \{# This *will* end up in the output, including delimiters #} | |
317 This too. | |
318 | |
319 | |
320 .. _legacy: | |
321 | |
322 --------------------------- | |
323 Legacy Text Template Syntax | |
324 --------------------------- | |
325 | |
326 The syntax for text templates was redesigned in version 0.5 of Genshi to make | |
327 the language more flexible and powerful. The older syntax is based on line | |
328 starting with dollar signs, similar to e.g. Cheetah_ or Velocity_. | |
329 | |
330 .. _cheetah: http://cheetahtemplate.org/ | |
331 .. _velocity: http://jakarta.apache.org/velocity/ | |
332 | |
333 A simple template using the old syntax looked like this: | |
334 | |
335 .. code-block:: genshitext | |
336 | |
337 Dear $name, | |
338 | |
339 We have the following items for you: | |
340 #for item in items | |
341 * $item | |
342 #end | |
343 | |
344 All the best, | |
345 Foobar | |
346 | |
347 Beyond the requirement of putting directives on separate lines prefixed with | |
348 dollar signs, the language itself is very similar to the new one. Except that | |
349 comments are lines that start with two ``#`` characters, and a line-break at the | |
350 end of a directive is removed automatically. | |
351 | |
352 .. note:: If you're using this old syntax, it is strongly recommended to | |
353 migrate to the new syntax. Simply replace any references to | |
354 ``TextTemplate`` by ``NewTextTemplate`` (and also change the | |
355 text templates, of course). On the other hand, if you want to stick | |
356 with the old syntax for a while longer, replace references to | |
357 ``TextTemplate`` by ``OldTextTemplate``; while ``TextTemplate`` is | |
358 still an alias for the old language at this point, that will change | |
359 in a future release. But also note that the old syntax may be | |
360 dropped entirely in a future release. |