Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 429:691dd56c0dd0 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for code blocks and changed error handling.
author cmlenz
date Thu, 22 Mar 2007 17:00:09 +0000
parents cab6b0256019
children 97544725bb7f
rev   line source
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
3 =============================
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
4 Genshi Text Template Language
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
5 =============================
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
6
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
7 In addition to the XML-based template language, Genshi provides a simple
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
8 text-based template language, intended for basic plain text generation needs.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
9 The language is similar to Cheetah_ or Velocity_.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
10
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
11 .. _cheetah: http://cheetahtemplate.org/
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
12 .. _velocity: http://jakarta.apache.org/velocity/
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
13
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
14 This document describes the template language and will be most useful as
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
15 reference to those developing Genshi text templates. Templates are XML files of some
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
16 kind (such as XHTML) that include processing directives_ (elements or
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
17 attributes identified by a separate namespace) that affect how the template is
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
18 rendered, and template expressions_ that are dynamically substituted by
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
19 variable data.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
20
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
21
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
22 .. contents:: Contents
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
23 :depth: 3
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
24 .. sectnum::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
25
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
26 ----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
27 Python API
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
28 ----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
29
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
30 The Python code required for templating with Genshi is generally based on the
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
31 following pattern:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
32
244
fa07ab5a7e53 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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
34 template source. This can either be done directly, or through a
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
35 ``TemplateLoader`` instance.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
36 * Call the ``generate()`` method of the template, passing any data that should
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
37 be made available to the template as keyword arguments.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
38 * Serialize the resulting stream using its ``render()`` method.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
39
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
40 For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
41
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
42 from genshi.template import TextTemplate
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
43
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
44 tmpl = TextTemplate('$title')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
45 stream = tmpl.generate(title='Hello, world!')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
46 print stream.render('text')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
47
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
48 That code would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
49
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
50 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
51
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
52 Using a template loader provides the advantage that “compiled” templates are
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
53 automatically cached, and only parsed again when the template file changes::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
54
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
55 from genshi.template import TemplateLoader
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
56
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
57 loader = TemplateLoader([templates_dir])
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
58 tmpl = loader.load('test.txt' cls=TextTemplate)
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
59 stream = tmpl.generate(title='Hello, world!')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
60 print stream.render('text')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
61
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
62
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
63 .. _`expressions`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
64
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
65 --------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
66 Template Expressions
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
67 --------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
68
244
fa07ab5a7e53 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
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
70 template data. Expressions need to prefixed with a dollar sign (``$``) and
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
71 usually enclosed in curly braces (``{…}``).
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
72
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
73 .. _python: http://www.python.org/
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
74
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
75 If the expression starts with a letter and contains only letters, digits, dots,
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
76 and underscores, the curly braces may be omitted. In all other cases, the
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
77 braces are required so that the template processor knows where the expression
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
78 ends::
241
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
429
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
95 Because there are two ways to access either attributes or items, expressions
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
96 do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
97 rather an exception of the type ``UndefinedError``. The same kind of error is
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
98 raised when you try to access a top-level variable that is not in the context
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
99 data.
244
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
100
429
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
101 Built-in Functions & Types
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
102 ==========================
244
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
103
429
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
104 The following functions and types are available by default in template code, in
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
105 addition to the standard built-ins that are available to all Python code.
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
106
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
107 ``defined(name)``
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
108 -----------------
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
109
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
110 This function determines whether a variable of the specified name exists in
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
111 the context data, and returns ``True`` if it does.
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
112
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
113 ``value_of(name, default=None)``
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
114 --------------------------------
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
115
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
116 This function returns the value of the variable with the specified name if
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
117 such a variable is defined, and returns the value of the ``default``
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
118 parameter if no such variable is defined.
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
119
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
120 ``Markup(text)``
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
121 ----------------
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
122
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
123 The ``Markup`` type marks a given string as being safe for inclusion in markup,
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
124 meaning it will *not* be escaped in the serialization stage. Use this with care,
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
125 as not escaping a user-provided string may allow malicious users to open your
691dd56c0dd0 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
126 web site to cross-site scripting attacks.
244
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
127
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
128
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129 .. _`directives`:
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 -------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
132 Template Directives
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
354
6951db75824e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
135 Directives are lines starting with a ``#`` character followed immediately by
6951db75824e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
136 the directive name. They can affect how the template is rendered in a number of
244
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
137 ways: Genshi provides directives for conditionals and looping, among others.
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
138
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
139 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
140 first non-whitespace character on that line. Each directive must be “closed”
246
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
141 using a ``#end`` marker. You can add after the ``#end`` marker, for example to
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
142 document which directive is being closed, or even the expression associated with
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
143 that directive. Any text after ``#end`` (but on the same line) is ignored,
c7dd64bcde9c Document that `#end` markers in text templates can be used as comments.
cmlenz
parents: 244
diff changeset
144 and effectively treated as a comment.
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145
244
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
146 If you want to include a literal ``#`` in the output, you need to escape it
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
147 by prepending a backslash character (``\``). Note that this is **not** required
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
148 if the ``#`` isn't immediately followed by a letter, or it isn't the first
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
149 non-whitespace character on the line.
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
150
241
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 Conditional Sections
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 ====================
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
154
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155 .. _`#if`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
156
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
157 ``#if``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
158 ---------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
159
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
160 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
161
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
162 #if foo
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 ${bar}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
166 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
167 would produce::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
168
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
169 Hello
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
170
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
171
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172 .. _`#choose`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
173 .. _`#when`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 .. _`#otherwise`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
175
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176 ``#choose``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177 -------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
178
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 The ``#choose`` directive, in combination with the directives ``#when`` and
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
180 ``#otherwise`` provides advanced contional processing for rendering one of
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
181 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
182 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
183
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
184 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
185 will be tested for truth::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
186
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
187 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
188 #choose
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
189 #when 0 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
190 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
191 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 #when 1 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
193 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
194 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
196 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
197 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
198 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
199
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
200 This would produce the following output::
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 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
203 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
204
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
205 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
206 be tested for equality to the parent ``#choose`` value::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
207
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
208 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
209 #choose 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
210 #when 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
211 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
212 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
213 #when 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
214 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
215 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
216 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
217 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
218 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
219 #end
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 This would produce the following output::
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 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
224 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
225
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
226
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
227 Looping
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
228 =======
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
229
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
230 .. _`#for`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
231
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
232 ``#for``
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
235 The content is repeated for every item in an iterable::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
236
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
237 Your items:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 #for item in items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239 * ${item}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
240 #end
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 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
243
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
244 Your items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
245 * 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
246 * 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
247 * 3
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250 Snippet Reuse
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
253 .. _`#def`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
254 .. _`macros`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
255
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
256 ``#def``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
257 ----------
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 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
260 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
261 in other places::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
262
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
263 #def greeting(name)
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
264 Hello, ${name}!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
265 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
266 ${greeting('world')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
267 ${greeting('everyone else')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
268
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
269 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
270
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
271 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
272 Hello, everyone else!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
273
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
274 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
275 without the parenthesis. For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
276
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
277 #def greeting
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
278 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
279 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
280 ${greeting}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
281
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
282 The above would be rendered to::
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 Hello, world!
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 Variable Binding
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 .. _`#with`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
291
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
292 ``#with``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
293 -----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
294
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
295 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
296 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
297 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
298 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
299 to a variable using this directive would probably help.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
300
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
301 For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
302
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
303 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
304 #with y=7; z=x+10
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
305 $x $y $z
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
306 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
307
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
308 Given ``x=42`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
309
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
310 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
311 42 7 52
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
312
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
313 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
314 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
315 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
316 this means that variables are immutable in Genshi.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
317
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
318
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
319 .. _comments:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
320
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
321 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
322 Comments
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
323 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
324
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
325 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
326 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
327 backslash.
Copyright (C) 2012-2017 Edgewall Software