Mercurial > genshi > mirror
annotate doc/text-templates.txt @ 315:b12c045c1e81 stable-0.3.x
Ported [383:387] to 0.3.x stable branch.
author | cmlenz |
---|---|
date | Tue, 24 Oct 2006 15:00:27 +0000 |
parents | c7dd64bcde9c |
children | 6951db75824e |
rev | line source |
---|---|
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
1 .. -*- mode: rst; encoding: utf-8 -*- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
2 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
3 ============================= |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
4 Genshi Text Template Language |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
5 ============================= |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
6 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
7 In addition to the XML-based template language, Genshi provides a simple |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
8 text-based template language, intended for basic plain text generation needs. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
9 The language is similar to Cheetah_ or Velocity_. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
10 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
11 .. _cheetah: http://cheetahtemplate.org/ |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
12 .. _velocity: http://jakarta.apache.org/velocity/ |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
13 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
14 This document describes the template language and will be most useful as |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
15 reference to those developing Genshi text templates. Templates are XML files of some |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
16 kind (such as XHTML) that include processing directives_ (elements or |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
17 attributes identified by a separate namespace) that affect how the template is |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
18 rendered, and template expressions_ that are dynamically substituted by |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
19 variable data. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
20 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
21 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
22 .. contents:: Contents |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
23 :depth: 3 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
24 .. sectnum:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
25 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
26 ---------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
27 Python API |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
28 ---------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
29 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
30 The Python code required for templating with Genshi is generally based on the |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
31 following pattern: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
32 |
244 | 33 * Attain a ``TextTemplate`` object from a string or file object containing the |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
34 template source. This can either be done directly, or through a |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
35 ``TemplateLoader`` instance. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
36 * Call the ``generate()`` method of the template, passing any data that should |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
37 be made available to the template as keyword arguments. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
38 * Serialize the resulting stream using its ``render()`` method. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
39 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
40 For example:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
41 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
42 from genshi.template import TextTemplate |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
43 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
44 tmpl = TextTemplate('$title') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
45 stream = tmpl.generate(title='Hello, world!') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
46 print stream.render('text') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
47 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
48 That code would produce the following output:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
49 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
50 Hello, world! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
51 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
52 Using a template loader provides the advantage that “compiled” templates are |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
53 automatically cached, and only parsed again when the template file changes:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
54 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
55 from genshi.template import TemplateLoader |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
56 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
57 loader = TemplateLoader([templates_dir]) |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
58 tmpl = loader.load('test.txt' cls=TextTemplate) |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
59 stream = tmpl.generate(title='Hello, world!') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
60 print stream.render('text') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
61 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
62 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
63 .. _`expressions`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
64 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
65 -------------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
66 Template Expressions |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
67 -------------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
68 |
244 | 69 Python_ expressions can be used in text and as arguments to directives_. An expression is substituted with the result of its evaluation against the |
70 template data. Expressions need to prefixed with a dollar sign (``$``) and | |
71 usually enclosed in curly braces (``{…}``). | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
72 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
73 .. _python: http://www.python.org/ |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
74 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
75 If the expression starts with a letter and contains only letters and digits, |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
76 the curly braces may be omitted. In all other cases, the braces are required |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
77 so that the template processors knows where the expression ends:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
78 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
79 >>> from genshi.template import TextTemplate |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
80 >>> tmpl = TextTemplate('${items[0].capitalize()} item') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
81 >>> print tmpl.generate(items=['first', 'second']) |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
82 First item |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
83 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
84 Expressions support the full power of Python. In addition, it is possible to |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
85 access items in a dictionary using “dotted notation” (i.e. as if they were |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
86 attributes), and vice-versa (i.e. access attributes as if they were items in |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
87 a dictionary):: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
88 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
89 >>> from genshi.template import TextTemplate |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
90 >>> tmpl = TextTemplate('${dict.foo}') |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
91 >>> print tmpl.generate(dict={'foo': 'bar'}) |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
92 bar |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
93 |
244 | 94 Another difference is that you can access variables that are not defined, and |
95 won't get a ``NameError`` exception:: | |
96 | |
97 >>> from genshi.template import TextTemplate | |
98 >>> tmpl = TextTemplate('${doh}') | |
99 >>> print tmpl.generate() | |
100 <BLANKLINE> | |
101 | |
102 You **will** however get a ``NameError`` if you try to call an undefined | |
103 variable, or do anything else with it, such as accessing its attributes. If you | |
104 need to know whether a variable is defined, you can check its type against the | |
105 ``Undefined`` class, for example in an `#if`_ directive:: | |
106 | |
107 >>> from genshi.template import TextTemplate | |
108 >>> tmpl = TextTemplate('${type(doh) is Undefined}') | |
109 >>> print tmpl.generate() | |
110 True | |
111 | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
112 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
113 .. _`directives`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
114 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
115 ------------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
116 Template Directives |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
117 ------------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
118 |
244 | 119 Directives are lines starting with a ``#`` character followed immediately by the directive name. They can affect how the template is rendered in a number of |
120 ways: Genshi provides directives for conditionals and looping, among others. | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
121 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
122 Directives must be on separate lines, and the ``#`` character must be be the |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
123 first non-whitespace character on that line. Each directive must be “closed” |
246
c7dd64bcde9c
Document that `#end` markers in text templates can be used as comments.
cmlenz
parents:
244
diff
changeset
|
124 using a ``#end`` marker. You can add after the ``#end`` marker, for example to |
c7dd64bcde9c
Document that `#end` markers in text templates can be used as comments.
cmlenz
parents:
244
diff
changeset
|
125 document which directive is being closed, or even the expression associated with |
c7dd64bcde9c
Document that `#end` markers in text templates can be used as comments.
cmlenz
parents:
244
diff
changeset
|
126 that directive. Any text after ``#end`` (but on the same line) is ignored, |
c7dd64bcde9c
Document that `#end` markers in text templates can be used as comments.
cmlenz
parents:
244
diff
changeset
|
127 and effectively treated as a comment. |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
128 |
244 | 129 If you want to include a literal ``#`` in the output, you need to escape it |
130 by prepending a backslash character (``\``). Note that this is **not** required | |
131 if the ``#`` isn't immediately followed by a letter, or it isn't the first | |
132 non-whitespace character on the line. | |
133 | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
134 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
135 Conditional Sections |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
136 ==================== |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
137 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
138 .. _`#if`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
139 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
140 ``#if`` |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
141 --------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
142 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
143 The content is only rendered if the expression evaluates to a truth value:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
144 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
145 #if foo |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
146 ${bar} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
147 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
148 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
149 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
150 would produce:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
151 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
152 Hello |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
153 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
154 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
155 .. _`#choose`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
156 .. _`#when`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
157 .. _`#otherwise`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
158 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
159 ``#choose`` |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
160 ------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
161 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
162 The ``#choose`` directive, in combination with the directives ``#when`` and |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
163 ``#otherwise`` provides advanced contional processing for rendering one of |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
164 several alternatives. The first matching ``#when`` branch is rendered, or, if |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
165 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
166 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
167 If the ``#choose`` directive has no argument the nested ``#when`` directives |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
168 will be tested for truth:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
169 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
170 The answer is: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
171 #choose |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
172 #when 0 == 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
173 0 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
174 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
175 #when 1 == 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
176 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
177 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
178 #otherwise |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
179 2 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
180 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
181 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
182 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
183 This would produce the following output:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
184 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
185 The answer is: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
186 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
187 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
188 If the ``#choose`` does have an argument, the nested ``#when`` directives will |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
189 be tested for equality to the parent ``#choose`` value:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
190 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
191 The answer is: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
192 #choose 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
193 #when 0 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
194 0 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
195 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
196 #when 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
197 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
198 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
199 #otherwise |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
200 2 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
201 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
202 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
203 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
204 This would produce the following output:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
205 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
206 The answer is: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
207 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
208 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
209 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
210 Looping |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
211 ======= |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
212 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
213 .. _`#for`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
214 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
215 ``#for`` |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
216 ---------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
217 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
218 The content is repeated for every item in an iterable:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
219 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
220 Your items: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
221 #for item in items |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
222 * ${item} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
223 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
224 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
225 Given ``items=[1, 2, 3]`` in the context data, this would produce:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
226 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
227 Your items |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
228 * 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
229 * 2 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
230 * 3 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
231 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
232 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
233 Snippet Reuse |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
234 ============= |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
235 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
236 .. _`#def`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
237 .. _`macros`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
238 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
239 ``#def`` |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
240 ---------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
241 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
242 The ``#def`` directive can be used to create macros, i.e. snippets of template |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
243 text that have a name and optionally some parameters, and that can be inserted |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
244 in other places:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
245 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
246 #def greeting(name) |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
247 Hello, ${name}! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
248 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
249 ${greeting('world')} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
250 ${greeting('everyone else')} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
251 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
252 The above would be rendered to:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
253 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
254 Hello, world! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
255 Hello, everyone else! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
256 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
257 If a macro doesn't require parameters, it can be defined as well as called |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
258 without the parenthesis. For example:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
259 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
260 #def greeting |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
261 Hello, world! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
262 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
263 ${greeting} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
264 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
265 The above would be rendered to:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
266 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
267 Hello, world! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
268 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
269 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
270 Variable Binding |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
271 ================ |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
272 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
273 .. _`#with`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
274 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
275 ``#with`` |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
276 ----------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
277 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
278 The ``#with`` directive lets you assign expressions to variables, which can |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
279 be used to make expressions inside the directive less verbose and more |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
280 efficient. For example, if you need use the expression ``author.posts`` more |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
281 than once, and that actually results in a database query, assigning the results |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
282 to a variable using this directive would probably help. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
283 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
284 For example:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
285 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
286 Magic numbers! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
287 #with y=7; z=x+10 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
288 $x $y $z |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
289 #end |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
290 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
291 Given ``x=42`` in the context data, this would produce:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
292 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
293 Magic numbers! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
294 42 7 52 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
295 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
296 Note that if a variable of the same name already existed outside of the scope |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
297 of the ``#with`` directive, it will **not** be overwritten. Instead, it will |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
298 have the same value it had prior to the ``#with`` assignment. Effectively, |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
299 this means that variables are immutable in Genshi. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
300 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
301 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
302 .. _comments: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
303 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
304 -------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
305 Comments |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
306 -------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
307 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
308 Lines where the first non-whitespace characters are ``##`` are removed from |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
309 the output, and can thus be used for comments. This can be escaped using a |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
310 backslash. |