Mercurial > genshi > genshi-test

annotate doc/text-templates.txt @ 376:74b6bf92f0cd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix parsing of processing instructions in HTML input.
author cmlenz
date Thu, 23 Nov 2006 11:28:15 +0000
parents 7ae694e7462e
children ebc7c1a3bc4d
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
354
7ae694e7462e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
119 Directives are lines starting with a ``#`` character followed immediately by
7ae694e7462e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
120 the directive name. They can affect how the template is rendered in a number of
244
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
121 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
122
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
123 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
124 first non-whitespace character on that line. Each directive must be “closed”
246
6fc4edebe12c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
125 using a ``#end`` marker. You can add after the ``#end`` marker, for example to
6fc4edebe12c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
126 document which directive is being closed, or even the expression associated with
6fc4edebe12c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
127 that directive. Any text after ``#end`` (but on the same line) is ignored,
6fc4edebe12c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
128 and effectively treated as a comment.
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129
244
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
130 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
131 by prepending a backslash character (``\``). Note that this is **not** required
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
132 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
133 non-whitespace character on the line.
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
134
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
135
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
136 Conditional Sections
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
137 ====================
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 .. _`#if`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
140
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
141 ``#if``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
142 ---------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
143
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
144 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
145
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
146 #if foo
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
147 ${bar}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
148 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
149
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
150 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
151 would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
152
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 Hello
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
154
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 .. _`#when`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
158 .. _`#otherwise`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
159
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
160 ``#choose``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
161 -------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
162
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 The ``#choose`` directive, in combination with the directives ``#when`` and
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164 ``#otherwise`` provides advanced contional processing for rendering one of
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165 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
166 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
167
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
168 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
169 will be tested for truth::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
170
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
171 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172 #choose
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
173 #when 0 == 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
175 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176 #when 1 == 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177 1
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 #otherwise
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
180 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
181 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
183
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
184 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
185
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
186 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
187 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
188
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
189 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
190 be tested for equality to the parent ``#choose`` value::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
191
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
193 #choose 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
194 #when 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
196 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
197 #when 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
198 1
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 #otherwise
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
201 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
202 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
203 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
204
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
205 This would produce the following output::
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 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
208 1
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
211 Looping
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
212 =======
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 .. _`#for`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
215
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
216 ``#for``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
217 ----------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
218
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
219 The content is repeated for every item in an iterable::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
220
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
221 Your items:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
222 #for item in items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
223 * ${item}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
224 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
225
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
226 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
227
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
228 Your items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
229 * 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
230 * 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
231 * 3
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
234 Snippet Reuse
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
237 .. _`#def`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 .. _`macros`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
240 ``#def``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
241 ----------
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 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
244 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
245 in other places::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
246
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
247 #def greeting(name)
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
248 Hello, ${name}!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
249 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250 ${greeting('world')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
251 ${greeting('everyone else')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
252
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
253 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
254
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
255 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
256 Hello, everyone else!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
257
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
258 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
259 without the parenthesis. For example::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
260
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
261 #def greeting
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
262 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
263 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
264 ${greeting}
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 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
267
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
268 Hello, world!
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
271 Variable Binding
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
272 ================
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 .. _`#with`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
275
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
276 ``#with``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
277 -----------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
278
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
279 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
280 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
281 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
282 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
283 to a variable using this directive would probably help.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
284
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
285 For example::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
286
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
287 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
288 #with y=7; z=x+10
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
289 $x $y $z
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
290 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
291
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
292 Given ``x=42`` in the context data, this would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
293
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
294 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
295 42 7 52
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
296
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
297 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
298 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
299 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
300 this means that variables are immutable in Genshi.
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
303 .. _comments:
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 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
306 Comments
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
307 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
308
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
309 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
310 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
311 backslash.
Copyright (C) 2012-2017 Edgewall Software