Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 500:3eb30e4ece8c experimental-inline

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged revisions 487-603 via svnmerge from http://svn.edgewall.org/repos/genshi/trunk
author cmlenz
date Fri, 01 Jun 2007 17:21:47 +0000
parents a81675590258
children 9755836bb396
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
500
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
15 reference to those developing Genshi text templates. Templates are text files of
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
16 some kind that include processing directives_ that affect how the template is
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
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
500
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
20 See `Genshi Templating Basics <templates.html>`_ for general information on
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
21 embedding Python code in templates.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
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
355
94639584725a inline branch: Merged [430:434/trunk].
cmlenz
parents: 246
diff changeset
35 Directives are lines starting with a ``#`` character followed immediately by
94639584725a inline branch: Merged [430:434/trunk].
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
500
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
187 .. _includes:
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
188 .. _`#include`:
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
189
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
190 ``#include``
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
191 ------------
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
192
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
193 To reuse common parts of template text across template files, you can include
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
194 other files using the ``#include`` directive::
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
195
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
196 #include "base.txt"
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
197
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
198 Any content included this way is inserted into the generated output. The
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
199 included template sees the context data as it exists at the point of the
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
200 include. `Macros`_ in the included template are also available to the including
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
201 template after the point it was included.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
202
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
203 Include paths are relative to the filename of the template currently being
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
204 processed. So if the example above was in the file "``myapp/mail.txt``"
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
205 (relative to the template search path), the include directive would look for
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
206 the included file at "``myapp/base.txt``". You can also use Unix-style
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
207 relative paths, for example "``../base.txt``" to look in the parent directory.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
208
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
209 Just like other directives, the argument to the ``#include`` directive accepts
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
210 any Python expression, so the path to the included template can be determined
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
211 dynamically::
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
212
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
213 #include '%s.txt' % filename
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
214
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
215 Note that a ``TemplateNotFound`` exception is raised if an included file can't
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
216 be found.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
217
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
218 .. note:: The include directive for text templates was added in Genshi 0.5.
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
219
3eb30e4ece8c Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
220
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
221 Variable Binding
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
224 .. _`#with`:
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 ``#with``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
227 -----------
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 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
230 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
231 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
232 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
233 to a variable using this directive would probably help.
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 For example::
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 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 #with y=7; z=x+10
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239 $x $y $z
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 ``x=42`` 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 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
245 42 7 52
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
246
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
247 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
248 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
249 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
250 this means that variables are immutable in Genshi.
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 .. _comments:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
254
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 Comments
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 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
260 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
261 backslash.
Copyright (C) 2012-2017 Edgewall Software