Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 451:4183fd29fa4e trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix broken link in documentation.
author cmlenz
date Sat, 14 Apr 2007 22:29:09 +0000
parents 97544725bb7f
children 477fac8052e3 26cf27d4f2b3
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
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
15 reference to those developing Genshi text templates. Templates are text files of
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
16 some kind that include processing directives_ that affect how the template is
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
17 rendered, and template expressions that are dynamically substituted by
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
18 variable data.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
19
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
20 See `Genshi Templating Basics <templates.html>`_ for general information on
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
21 embedding Python code in templates.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
22
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
23
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
24 .. contents:: Contents
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
25 :depth: 3
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
26 .. sectnum::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
27
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 .. _`directives`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
30
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
31 -------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
32 Template Directives
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
33 -------------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
34
354
6951db75824e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
35 Directives are lines starting with a ``#`` character followed immediately by
6951db75824e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
36 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
37 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
38
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
39 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
40 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
41 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
42 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
43 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
44 and effectively treated as a comment.
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
45
244
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
46 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
47 by prepending a backslash character (``\``). Note that this is **not** required
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
48 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
49 non-whitespace character on the line.
fa07ab5a7e53 Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
50
241
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 Conditional Sections
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
53 ====================
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 .. _`#if`:
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 ``#if``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
58 ---------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
59
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
60 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
61
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
62 #if foo
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
63 ${bar}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
64 #end
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 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
67 would produce::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
68
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
69 Hello
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
70
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
71
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
72 .. _`#choose`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
73 .. _`#when`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
74 .. _`#otherwise`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
75
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
76 ``#choose``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
77 -------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
78
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
79 The ``#choose`` directive, in combination with the directives ``#when`` and
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
80 ``#otherwise`` provides advanced contional processing for rendering one of
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81 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
82 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
83
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
84 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
85 will be tested for truth::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
86
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
87 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
88 #choose
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
89 #when 0 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
90 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
91 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
92 #when 1 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
93 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
94 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
95 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
96 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
97 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
98 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
99
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
100 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
101
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
102 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
103 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
104
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
105 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
106 be tested for equality to the parent ``#choose`` value::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
107
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
108 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
109 #choose 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
110 #when 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
111 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
112 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
113 #when 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
114 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
115 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
116 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
117 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
118 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
119 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
120
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
121 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
122
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
123 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
124 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
125
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
126
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
127 Looping
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
130 .. _`#for`:
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 ``#for``
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
135 The content is repeated for every item in an iterable::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
136
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
137 Your items:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
138 #for item in items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
139 * ${item}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
140 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
141
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
142 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
143
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
144 Your items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145 * 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
146 * 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
147 * 3
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
148
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
149
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
150 Snippet Reuse
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 .. _`#def`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
154 .. _`macros`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
156 ``#def``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
157 ----------
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 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
160 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
161 in other places::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
162
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163 #def greeting(name)
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164 Hello, ${name}!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
166 ${greeting('world')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
167 ${greeting('everyone else')}
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 The above would be rendered to::
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 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172 Hello, everyone else!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
173
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 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
175 without the parenthesis. For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177 #def greeting
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
178 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
180 ${greeting}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
181
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182 The above would be rendered to::
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 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
185
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
186
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
187 Variable Binding
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
188 ================
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
189
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
190 .. _`#with`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
191
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 ``#with``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
193 -----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
194
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195 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
196 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
197 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
198 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
199 to a variable using this directive would probably help.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
200
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
201 For example::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
202
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
203 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
204 #with y=7; z=x+10
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
205 $x $y $z
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
206 #end
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 Given ``x=42`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
209
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
210 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
211 42 7 52
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
212
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
213 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
214 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
215 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
216 this means that variables are immutable in Genshi.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
217
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
218
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
219 .. _comments:
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 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
222 Comments
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
223 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
224
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
225 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
226 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
227 backslash.
Copyright (C) 2012-2017 Edgewall Software