Mercurial > genshi > mirror

annotate doc/text-templates.txt @ 554:0cdbd6e5831e experimental-newctxt

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New experimental branch for trying a different approach at context data stack management and simplified code evaluation/execution.
author cmlenz
date Mon, 02 Jul 2007 17:24:32 +0000
parents 1bdccd3bda00
children 1da8de3e5e51 acf7c5ee36e7
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
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
60 The content is only rendered if the expression evaluates to a truth value:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
61
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
62 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
63
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
64 #if foo
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
65 ${bar}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
66 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
67
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
68 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
69 would produce::
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 Hello
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
72
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
73
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
74 .. _`#choose`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
75 .. _`#when`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
76 .. _`#otherwise`:
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 ``#choose``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
79 -------------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
80
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81 The ``#choose`` directive, in combination with the directives ``#when`` and
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
82 ``#otherwise`` provides advanced contional processing for rendering one of
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
83 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
84 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
85
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
86 If the ``#choose`` directive has no argument the nested ``#when`` directives
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
87 will be tested for truth:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
88
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
89 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
90
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
91 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
92 #choose
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
93 #when 0 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
94 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
95 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
96 #when 1 == 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
97 1
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 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
100 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
101 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
102 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
103
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
104 This would produce the following output::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
105
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
106 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
107 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
108
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
109 If the ``#choose`` does have an argument, the nested ``#when`` directives will
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
110 be tested for equality to the parent ``#choose`` value:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
111
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
112 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
113
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
114 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
115 #choose 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
116 #when 0
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
117 0
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 #when 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
120 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
121 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
122 #otherwise
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
123 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
124 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
125 #end
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 This would produce the following output::
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 The answer is:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
130 1
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
133 Looping
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
136 .. _`#for`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
137
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
138 ``#for``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
139 ----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
140
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
141 The content is repeated for every item in an iterable:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
142
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
143 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
144
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145 Your items:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
146 #for item in items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
147 * ${item}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
148 #end
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 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
151
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
152 Your items
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 * 1
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
154 * 2
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155 * 3
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
156
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
157
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
158 Snippet Reuse
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
159 =============
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
160
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
161 .. _`#def`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
162 .. _`macros`:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164 ``#def``
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165 ----------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
166
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
167 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
168 text that have a name and optionally some parameters, and that can be inserted
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
169 in other places:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
170
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
171 .. code-block:: genshitext
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
173 #def greeting(name)
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 Hello, ${name}!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
175 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176 ${greeting('world')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177 ${greeting('everyone else')}
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
178
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
180
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
181 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182 Hello, everyone else!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
183
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
184 If a macro doesn't require parameters, it can be defined as well as called
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
185 without the parenthesis. For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
186
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
187 .. code-block:: genshitext
241
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 #def greeting
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
190 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
191 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 ${greeting}
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 The above would be rendered to::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
196 Hello, world!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
197
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
198
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
199 .. _includes:
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
200 .. _`#include`:
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
201
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
202 ``#include``
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
203 ------------
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
204
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
205 To reuse common parts of template text across template files, you can include
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
206 other files using the ``#include`` directive:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
207
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
208 .. code-block:: genshitext
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
209
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
210 #include "base.txt"
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
211
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
212 Any content included this way is inserted into the generated output. The
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
213 included template sees the context data as it exists at the point of the
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
214 include. `Macros`_ in the included template are also available to the including
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
215 template after the point it was included.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
216
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
217 Include paths are relative to the filename of the template currently being
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
218 processed. So if the example above was in the file "``myapp/mail.txt``"
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
219 (relative to the template search path), the include directive would look for
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
220 the included file at "``myapp/base.txt``". You can also use Unix-style
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
221 relative paths, for example "``../base.txt``" to look in the parent directory.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
222
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
223 Just like other directives, the argument to the ``#include`` directive accepts
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
224 any Python expression, so the path to the included template can be determined
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
225 dynamically:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
226
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
227 .. code-block:: genshitext
477
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
228
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
229 #include '%s.txt' % filename
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
230
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
231 Note that a ``TemplateNotFound`` exception is raised if an included file can't
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
232 be found.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
233
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
234 .. note:: The include directive for text templates was added in Genshi 0.5.
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
235
477fac8052e3 Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
236
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
237 Variable Binding
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 ================
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
240 .. _`#with`:
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 ``#with``
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
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
245 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
246 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
247 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
248 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
249 to a variable using this directive would probably help.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
251 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
252
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
253 .. code-block:: genshitext
241
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 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
256 #with y=7; z=x+10
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
257 $x $y $z
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
258 #end
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
259
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
260 Given ``x=42`` in the context data, this would produce::
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
261
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
262 Magic numbers!
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
263 42 7 52
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
264
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
265 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
266 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
267 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
268 this means that variables are immutable in Genshi.
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
269
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
270
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
271 .. _comments:
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
272
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
273 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
274 Comments
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
275 --------
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
276
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
277 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
278 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
279 backslash.
Copyright (C) 2012-2017 Edgewall Software