Mercurial > genshi > genshi-test

annotate doc/text-templates.txt @ 439:b84c11a49ad2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add support for adding custom template filters by passing a custom callback function to the `TemplateLoader`. Closes #89 (see added unit test).
author cmlenz
date Mon, 02 Apr 2007 19:43:31 +0000
parents 6911f3c5a7e8
children ff7c72b52fb2
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
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
75 If the expression starts with a letter and contains only letters, digits, dots,
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
76 and underscores, the curly braces may be omitted. In all other cases, the
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
77 braces are required so that the template processor knows where the expression
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
78 ends::
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
79
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
80 >>> from genshi.template import TextTemplate
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81 >>> tmpl = TextTemplate('${items[0].capitalize()} item')
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
82 >>> print tmpl.generate(items=['first', 'second'])
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
83 First item
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
84
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
88 a dictionary)::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
89
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
90 >>> from genshi.template import TextTemplate
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
91 >>> tmpl = TextTemplate('${dict.foo}')
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
92 >>> print tmpl.generate(dict={'foo': 'bar'})
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
93 bar
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
94
429
6911f3c5a7e8 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
6911f3c5a7e8 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
6911f3c5a7e8 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
6911f3c5a7e8 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
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
99 data.
244
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
100
429
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
101 Built-in Functions & Types
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
102 ==========================
244
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
103
429
6911f3c5a7e8 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
6911f3c5a7e8 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.
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
106
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
107 ``defined(name)``
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
108 -----------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
109
6911f3c5a7e8 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
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
111 the context data, and returns ``True`` if it does.
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
112
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
113 ``value_of(name, default=None)``
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
114 --------------------------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
115
6911f3c5a7e8 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
6911f3c5a7e8 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``
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
118 parameter if no such variable is defined.
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
119
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
120 ``Markup(text)``
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
121 ----------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
122
6911f3c5a7e8 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,
6911f3c5a7e8 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,
6911f3c5a7e8 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
6911f3c5a7e8 Updated docs for code blocks and changed error handling.
cmlenz
parents: 394
diff changeset
126 web site to cross-site scripting attacks.
244
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
127
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
128
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129 .. _`directives`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
130
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 Template Directives
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
354
7ae694e7462e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
135 Directives are lines starting with a ``#`` character followed immediately by
7ae694e7462e 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
137 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
138
bbed6d426678 * 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
bbed6d426678 * 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
6fc4edebe12c 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
6fc4edebe12c 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
6fc4edebe12c 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,
6fc4edebe12c 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145
244
78ae64ef822e 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
147 by prepending a backslash character (``\``). Note that this is **not** required
78ae64ef822e 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
149 non-whitespace character on the line.
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
150
241
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 Conditional Sections
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 ====================
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 .. _`#if`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
156
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
157 ``#if``
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
bbed6d426678 * 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::
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 #if foo
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 ${bar}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
167 would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
168
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
169 Hello
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
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`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 .. _`#otherwise`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
175
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176 ``#choose``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177 -------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
178
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 The ``#choose`` directive, in combination with the directives ``#when`` and
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
180 ``#otherwise`` provides advanced contional processing for rendering one of
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
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 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
185 will be tested for truth::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
186
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
187 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
188 #choose
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
189 #when 0 == 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
190 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
191 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 #when 1 == 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
193 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
194 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195 #otherwise
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
196 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
197 #end
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
200 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
201
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
202 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
203 1
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 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
206 be tested for equality to the parent ``#choose`` value::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
207
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
208 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
209 #choose 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
210 #when 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
211 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
212 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
213 #when 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
214 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
215 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
216 #otherwise
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
217 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
218 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
219 #end
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 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
222
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
223 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
224 1
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
227 Looping
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 .. _`#for`:
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 ``#for``
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
235 The content is repeated for every item in an iterable::
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 Your items:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 #for item in items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239 * ${item}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
240 #end
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 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
243
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
244 Your items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
245 * 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
246 * 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
247 * 3
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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250 Snippet Reuse
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
251 =============
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 .. _`#def`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
254 .. _`macros`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
255
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
256 ``#def``
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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
261 in other places::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
262
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
263 #def greeting(name)
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
264 Hello, ${name}!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
265 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
266 ${greeting('world')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
267 ${greeting('everyone else')}
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 The above would be rendered to::
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 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
272 Hello, everyone else!
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 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
275 without the parenthesis. For example::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
276
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
277 #def greeting
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
278 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
279 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
280 ${greeting}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
281
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
282 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
283
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
284 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
285
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 Variable Binding
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
288 ================
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 .. _`#with`:
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 ``#with``
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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
299 to a variable using this directive would probably help.
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 For example::
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 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
304 #with y=7; z=x+10
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
305 $x $y $z
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
306 #end
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 Given ``x=42`` in the context data, this would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
309
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
310 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
311 42 7 52
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
312
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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,
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
316 this means that variables are immutable in Genshi.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
317
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
318
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
319 .. _comments:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
320
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
321 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
322 Comments
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
323 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
324
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
327 backslash.
Copyright (C) 2012-2017 Edgewall Software