Mercurial > genshi > genshi-test

annotate doc/text-templates.txt @ 244:78ae64ef822e

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