Mercurial > genshi > genshi-test

annotate doc/text-templates.txt @ 575:7950b266c97d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Ensure that content gets added after the end of a stream.
author athomas
date Mon, 23 Jul 2007 04:22:20 +0000
parents ca7d707d51b0
children 7145e4eba2ec f0bb2c5ea0ff
rev   line source
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
3 =============================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
4 Genshi Text Template Language
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
5 =============================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
6
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
7 In addition to the XML-based template language, Genshi provides a simple
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
8 text-based template language, intended for basic plain text generation needs.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
9 The language is similar to Cheetah_ or Velocity_.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
10
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
11 .. _cheetah: http://cheetahtemplate.org/
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
12 .. _velocity: http://jakarta.apache.org/velocity/
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
13
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
14 This document describes the template language and will be most useful as
442
ff7c72b52fb2 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
ff7c72b52fb2 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
ff7c72b52fb2 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
18 variable data.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
19
442
ff7c72b52fb2 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
ff7c72b52fb2 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.
ff7c72b52fb2 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
23
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
24 .. contents:: Contents
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
25 :depth: 3
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
26 .. sectnum::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
27
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
28
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
29 .. _`directives`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
30
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
31 -------------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
32 Template Directives
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
33 -------------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
34
354
7ae694e7462e Remove unused code from text template plugin.
cmlenz
parents: 246
diff changeset
35 Directives are lines starting with a ``#`` character followed immediately by
7ae694e7462e 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
37 ways: Genshi provides directives for conditionals and looping, among others.
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
38
bbed6d426678 * 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
bbed6d426678 * 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
6fc4edebe12c 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
6fc4edebe12c 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
6fc4edebe12c 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,
6fc4edebe12c 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
45
244
78ae64ef822e 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
47 by prepending a backslash character (``\``). Note that this is **not** required
78ae64ef822e 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
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
49 non-whitespace character on the line.
78ae64ef822e Fixes for the text template docs.
cmlenz
parents: 241
diff changeset
50
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
51
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
52 Conditional Sections
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
53 ====================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
54
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
55 .. _`#if`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
56
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
57 ``#if``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
58 ---------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
59
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
61
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
62 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
63
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
64 #if foo
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
65 ${bar}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
66 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
67
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
68 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
69 would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
70
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
71 Hello
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
72
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
73
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
74 .. _`#choose`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
75 .. _`#when`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
76 .. _`#otherwise`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
77
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
78 ``#choose``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
79 -------------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
80
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
81 The ``#choose`` directive, in combination with the directives ``#when`` and
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
82 ``#otherwise`` provides advanced contional processing for rendering one of
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
84 no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
85
bbed6d426678 * 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
87 will be tested for truth:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
88
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
89 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
90
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
91 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
92 #choose
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
93 #when 0 == 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
94 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
95 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
96 #when 1 == 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
97 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
98 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
99 #otherwise
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
100 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
101 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
102 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
103
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
104 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
105
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
106 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
107 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
108
bbed6d426678 * 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
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
111
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
112 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
113
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
114 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
115 #choose 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
116 #when 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
117 0
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
118 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
119 #when 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
120 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
121 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
122 #otherwise
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
123 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
124 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
125 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
126
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
127 This would produce the following output::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
128
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
129 The answer is:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
130 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
131
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
132
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
133 Looping
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
134 =======
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
135
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
136 .. _`#for`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
137
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
138 ``#for``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
139 ----------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
140
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
142
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
143 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
144
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
145 Your items:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
146 #for item in items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
147 * ${item}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
148 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
149
bbed6d426678 * 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::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
151
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
152 Your items
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
153 * 1
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
154 * 2
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
155 * 3
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
156
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
157
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
158 Snippet Reuse
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
159 =============
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
160
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
161 .. _`#def`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
162 .. _`macros`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
163
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
164 ``#def``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
165 ----------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
166
bbed6d426678 * 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
bbed6d426678 * 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
169 in other places:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
170
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
171 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
172
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
173 #def greeting(name)
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
174 Hello, ${name}!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
175 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
176 ${greeting('world')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
177 ${greeting('everyone else')}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
178
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
179 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
180
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
181 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
182 Hello, everyone else!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
183
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
184 If a macro doesn't require parameters, it can be defined as well as called
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
185 without the parenthesis. For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
186
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
187 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
188
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
189 #def greeting
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
190 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
191 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
192 ${greeting}
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
193
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
194 The above would be rendered to::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
195
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
196 Hello, world!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
197
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
198
477
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
199 .. _includes:
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
200 .. _`#include`:
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
201
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
202 ``#include``
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
203 ------------
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
204
2abf0a19058b 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
206 other files using the ``#include`` directive:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
207
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
208 .. code-block:: genshitext
477
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
209
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
210 #include "base.txt"
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
211
2abf0a19058b 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
2abf0a19058b 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
2abf0a19058b 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
215 template after the point it was included.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
216
2abf0a19058b 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
2abf0a19058b 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``"
2abf0a19058b 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
2abf0a19058b 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
2abf0a19058b 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.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
222
2abf0a19058b 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
2abf0a19058b 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
225 dynamically:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
226
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
227 .. code-block:: genshitext
477
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
228
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
229 #include '%s.txt' % filename
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
230
2abf0a19058b 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
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
232 be found.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
233
2abf0a19058b 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.
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
235
2abf0a19058b Update documentation to include the new #include directive in text templates.
cmlenz
parents: 442
diff changeset
236
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
237 Variable Binding
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
238 ================
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
239
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
240 .. _`#with`:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
242 ``#with``
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
243 -----------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
244
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
249 to a variable using this directive would probably help.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
250
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
251 For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
252
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 477
diff changeset
253 .. code-block:: genshitext
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
254
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
255 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
256 #with y=7; z=x+10
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
257 $x $y $z
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
258 #end
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
259
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
260 Given ``x=42`` in the context data, this would produce::
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
261
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
262 Magic numbers!
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
263 42 7 52
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
264
bbed6d426678 * 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
bbed6d426678 * 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
bbed6d426678 * 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,
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
268 this means that variables are immutable in Genshi.
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
269
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
270
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
271 .. _comments:
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
272
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
273 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
274 Comments
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
275 --------
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
276
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
277 Lines where the first non-whitespace characters are ``##`` are removed from
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
278 the output, and can thus be used for comments. This can be escaped using a
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents:
diff changeset
279 backslash.
Copyright (C) 2012-2017 Edgewall Software