Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 241:4d81439bc097 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Added basic documentation for the text-based template language. * Directives in text templates are now closed with a simple `#end` line instead of the longer `#end<name>`.
author cmlenz
date Wed, 13 Sep 2006 14:52:58 +0000
parents
children fa07ab5a7e53
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
33 * Attain a ``Template`` object from a string or file object containing the
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
69 Python_ expressions can be used in text and attribute values. An expression is
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
70 substituted with the result of its evaluation against the template data.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
71 Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
72 curly braces (``{…}``).
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
73
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
74 .. _python: http://www.python.org/
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
75
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
76 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
77 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
78 so that the template processors knows where the expression ends::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
79
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
80 >>> from genshi.template import TextTemplate
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81 >>> tmpl = TextTemplate('${items[0].capitalize()} item')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
82 >>> print tmpl.generate(items=['first', 'second'])
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
83 First item
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
84
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
85 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
86 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
87 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
88 a dictionary)::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
89
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
90 >>> from genshi.template import TextTemplate
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
91 >>> tmpl = TextTemplate('${dict.foo}')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
92 >>> print tmpl.generate(dict={'foo': 'bar'})
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
93 bar
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
94
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
95
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
96 .. _`directives`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
97
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
98 -------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
99 Template Directives
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
100 -------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
101
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
102 Directives are lines starting with a ``#`` character followed by the directive
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
103 name. They can affect how the template is rendered in a number of ways: Genshi
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
104 provides directives for conditionals and looping, among others.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
105
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
106 For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
107
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
108 #if foo
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
109 Bar
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
110 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
111
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
112 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
113 first non-whitespace character on that line. Each directive must be “closed”
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
114 using a ``#end`` marker.
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
117 Conditional Sections
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
118 ====================
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
119
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
120 .. _`#if`:
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 ``#if``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
123 ---------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
124
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
125 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
126
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
127 #if foo
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
128 ${bar}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
130
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
131 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
132 would produce::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
133
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
134 Hello
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
135
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 .. _`#choose`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
138 .. _`#when`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
139 .. _`#otherwise`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
140
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
141 ``#choose``
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
144 The ``#choose`` directive, in combination with the directives ``#when`` and
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145 ``#otherwise`` provides advanced contional processing for rendering one of
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
146 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
147 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
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 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
150 will be tested for truth::
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 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 #choose
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
154 #when 0 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
156 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
157 #when 1 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
158 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
159 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
160 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
161 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
162 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165 This would produce the following output::
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 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
168 1
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 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
171 be tested for equality to the parent ``#choose`` value::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
173 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 #choose 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
175 #when 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176 0
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 #when 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 1
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 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
183 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
184 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
185
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
186 This would produce the following output::
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 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
189 1
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 Looping
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
193 =======
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
194
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195 .. _`#for`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
196
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
197 ``#for``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
198 ----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
199
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
200 The content is repeated for every item in an iterable::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
201
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
202 Your items:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
203 #for item in items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
204 * ${item}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
205 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
206
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
207 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
208
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
209 Your items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
210 * 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
211 * 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
212 * 3
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
213
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 Snippet Reuse
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 .. _`#def`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
219 .. _`macros`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
220
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
221 ``#def``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
222 ----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
223
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
224 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
225 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
226 in other places::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
227
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
228 #def greeting(name)
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
229 Hello, ${name}!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
230 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
231 ${greeting('world')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
232 ${greeting('everyone else')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
233
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
234 The above would be rendered to::
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 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
237 Hello, everyone else!
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 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
240 without the parenthesis. For example::
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 #def greeting
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
243 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
244 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
245 ${greeting}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
246
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
247 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
248
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
249 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250
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 Variable Binding
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
255 .. _`#with`:
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 ``#with``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
258 -----------
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 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
261 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
262 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
263 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
264 to a variable using this directive would probably help.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
265
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
266 For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
267
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
268 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
269 #with y=7; z=x+10
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
270 $x $y $z
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
271 #end
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 Given ``x=42`` in the context data, this would produce::
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 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
276 42 7 52
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 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
279 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
280 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
281 this means that variables are immutable in Genshi.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
282
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 .. _comments:
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 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
287 Comments
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
288 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
289
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
290 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
291 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
292 backslash.
Copyright (C) 2012-2017 Edgewall Software