Mercurial > genshi > mirror
annotate doc/text-templates.txt @ 562:b3dc05d88751 trunk
In the py:choose stack, store the information of whether a test expression has been supplied separate from the result of its evaluation.
author | cmlenz |
---|---|
date | Thu, 05 Jul 2007 17:49:20 +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 | 35 Directives are lines starting with a ``#`` character followed immediately by |
36 the directive name. They can affect how the template is rendered in a number of | |
244 | 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 | 46 If you want to include a literal ``#`` in the output, you need to escape it |
47 by prepending a backslash character (``\``). Note that this is **not** required | |
48 if the ``#`` isn't immediately followed by a letter, or it isn't the first | |
49 non-whitespace character on the line. | |
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. |