Mercurial > genshi > mirror
annotate doc/text-templates.txt @ 820:9755836bb396 experimental-inline
Sync (old) experimental inline branch with trunk@1027.
author | cmlenz |
---|---|
date | Wed, 11 Mar 2009 17:51:06 +0000 |
parents | 3eb30e4ece8c |
children |
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. |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
9 The language is similar to the Django_ template language. |
241
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 This document describes the template language and will be most useful as |
500 | 12 reference to those developing Genshi text templates. Templates are text files of |
13 some kind that include processing directives_ that affect how the template is | |
14 rendered, and template expressions that are dynamically substituted by | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
15 variable data. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
16 |
500 | 17 See `Genshi Templating Basics <templates.html>`_ for general information on |
18 embedding Python code in templates. | |
19 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
20 .. note:: Actually, Genshi currently has two different syntaxes for text |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
21 templates languages: One implemented by the class ``OldTextTemplate`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
22 and another implemented by ``NewTextTemplate``. This documentation |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
23 concentrates on the latter, which is planned to completely replace the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
24 older syntax. The older syntax is briefly described under legacy_. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
25 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
26 .. _django: http://www.djangoproject.com/ |
241
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 .. contents:: Contents |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
29 :depth: 3 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
30 .. sectnum:: |
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 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
33 .. _`directives`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
34 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
35 ------------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
36 Template Directives |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
37 ------------------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
38 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
39 Directives are template commands enclosed by ``{% ... %}`` characters. They can |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
40 affect how the template is rendered in a number of ways: Genshi provides |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
41 directives for conditionals and looping, among others. |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
42 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
43 Each directive must be terminated using an ``{% end %}`` marker. You can add |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
44 a string inside the ``{% end %}`` marker, for example to document which |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
45 directive is being closed, or even the expression associated with that |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
46 directive. Any text after ``end`` inside the delimiters is ignored, and |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
47 effectively treated as a comment. |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
48 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
49 If you want to include a literal delimiter in the output, you need to escape it |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
50 by prepending a backslash character (``\``). |
244 | 51 |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
52 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
53 Conditional Sections |
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 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
56 .. _`if`: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
57 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
58 ``{% if %}`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
59 ------------ |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
60 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
61 The content is only rendered if the expression evaluates to a truth value: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
62 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
63 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
64 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
65 {% if foo %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
66 ${bar} |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
67 {% end %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
68 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
69 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
|
70 would produce:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
71 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
72 Hello |
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 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
75 .. _`choose`: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
76 .. _`when`: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
77 .. _`otherwise`: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
78 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
79 ``{% choose %}`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
80 ---------------- |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
81 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
82 The ``choose`` directive, in combination with the directives ``when`` and |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
83 ``otherwise``, provides advanced contional processing for rendering one of |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
84 several alternatives. The first matching ``when`` branch is rendered, or, if |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
85 no ``when`` branch matches, the ``otherwise`` branch is be rendered. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
86 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
87 If the ``choose`` directive has no argument the nested ``when`` directives will |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
88 be tested for truth: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
89 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
90 .. code-block:: genshitext |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
91 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
92 The answer is: |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
93 {% choose %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
94 {% when 0 == 1 %}0{% end %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
95 {% when 1 == 1 %}1{% end %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
96 {% otherwise %}2{% end %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
97 {% end %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
98 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
99 This would produce the following output:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
100 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
101 The answer is: |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
102 1 |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
103 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
104 If the ``choose`` does have an argument, the nested ``when`` directives will |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
105 be tested for equality to the parent ``choose`` value: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
106 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
107 .. code-block:: genshitext |
241
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 The answer is: |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
110 {% choose 1 %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
111 {% when 0 %}0{% end %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
112 {% when 1 %}1{% end %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
113 {% otherwise %}2{% end %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
114 {% end %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
115 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
116 This would produce the following output:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
117 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
118 The answer is: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
119 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
120 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
121 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
122 Looping |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
123 ======= |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
124 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
125 .. _`for`: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
126 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
127 ``{% for %}`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
128 ------------- |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
129 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
130 The content is repeated for every item in an iterable: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
131 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
132 .. code-block:: genshitext |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
133 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
134 Your items: |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
135 {% for item in items %}\ |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
136 * ${item} |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
137 {% end %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
138 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
139 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
|
140 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
141 Your items |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
142 * 1 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
143 * 2 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
144 * 3 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
145 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
146 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
147 Snippet Reuse |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
148 ============= |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
149 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
150 .. _`def`: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
151 .. _`macros`: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
152 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
153 ``{% def %}`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
154 ------------- |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
155 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
156 The ``def`` directive can be used to create macros, i.e. snippets of template |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
157 text that have a name and optionally some parameters, and that can be inserted |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
158 in other places: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
159 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
160 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
161 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
162 {% def greeting(name) %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
163 Hello, ${name}! |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
164 {% end %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
165 ${greeting('world')} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
166 ${greeting('everyone else')} |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
167 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
168 The above would be rendered to:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
169 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
170 Hello, world! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
171 Hello, everyone else! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
172 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
173 If a macro doesn't require parameters, it can be defined without the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
174 parenthesis. For example: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
175 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
176 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
177 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
178 {% def greeting %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
179 Hello, world! |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
180 {% end %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
181 ${greeting()} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
182 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
183 The above would be rendered to:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
184 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
185 Hello, world! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
186 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
187 |
500 | 188 .. _includes: |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
189 .. _`include`: |
500 | 190 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
191 ``{% include %}`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
192 ----------------- |
500 | 193 |
194 To reuse common parts of template text across template files, you can include | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
195 other files using the ``include`` directive: |
500 | 196 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
197 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
198 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
199 {% include base.txt %} |
500 | 200 |
201 Any content included this way is inserted into the generated output. The | |
202 included template sees the context data as it exists at the point of the | |
203 include. `Macros`_ in the included template are also available to the including | |
204 template after the point it was included. | |
205 | |
206 Include paths are relative to the filename of the template currently being | |
207 processed. So if the example above was in the file "``myapp/mail.txt``" | |
208 (relative to the template search path), the include directive would look for | |
209 the included file at "``myapp/base.txt``". You can also use Unix-style | |
210 relative paths, for example "``../base.txt``" to look in the parent directory. | |
211 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
212 Just like other directives, the argument to the ``include`` directive accepts |
500 | 213 any Python expression, so the path to the included template can be determined |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
214 dynamically: |
500 | 215 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
216 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
217 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
218 {% include ${'%s.txt' % filename} %} |
500 | 219 |
220 Note that a ``TemplateNotFound`` exception is raised if an included file can't | |
221 be found. | |
222 | |
223 .. note:: The include directive for text templates was added in Genshi 0.5. | |
224 | |
225 | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
226 Variable Binding |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
227 ================ |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
228 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
229 .. _`with`: |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
230 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
231 ``{% with %}`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
232 -------------- |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
233 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
234 The ``{% with %}`` directive lets you assign expressions to variables, which can |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
235 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
|
236 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
|
237 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
|
238 to a variable using this directive would probably help. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
239 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
240 For example: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
241 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
242 .. code-block:: genshitext |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
243 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
244 Magic numbers! |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
245 {% with y=7; z=x+10 %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
246 $x $y $z |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
247 {% end %} |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
248 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
249 Given ``x=42`` in the context data, this would produce:: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
250 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
251 Magic numbers! |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
252 42 7 52 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
253 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
254 Note that if a variable of the same name already existed outside of the scope |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
255 of the ``with`` directive, it will **not** be overwritten. Instead, it will |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
256 have the same value it had prior to the ``with`` assignment. Effectively, |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
257 this means that variables are immutable in Genshi. |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
258 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
259 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
260 .. _whitespace: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
261 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
262 --------------------------- |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
263 White-space and Line Breaks |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
264 --------------------------- |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
265 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
266 Note that space or line breaks around directives is never automatically removed. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
267 Consider the following example: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
268 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
269 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
270 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
271 {% for item in items %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
272 {% if item.visible %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
273 ${item} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
274 {% end %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
275 {% end %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
276 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
277 This will result in two empty lines above and beneath every item, plus the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
278 spaces used for indentation. If you want to supress a line break, simply end |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
279 the line with a backslash: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
280 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
281 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
282 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
283 {% for item in items %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
284 {% if item.visible %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
285 ${item} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
286 {% end %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
287 {% end %}\ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
288 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
289 Now there would be no empty lines between the items in the output. But you still |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
290 get the spaces used for indentation, and because the line breaks are removed, |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
291 they actually continue and add up between lines. There are numerous ways to |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
292 control white-space in the output while keeping the template readable, such as |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
293 moving the indentation into the delimiters, or moving the end delimiter on the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
294 next line, and so on. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
295 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
296 |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
297 .. _comments: |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
298 |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
299 -------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
300 Comments |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
301 -------- |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
302 |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
303 Parts in templates can be commented out using the delimiters ``{# ... #}``. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
304 Any content in comments are removed from the output. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
305 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
306 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
307 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
308 {# This won't end up in the output #} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
309 This will. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
310 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
311 Just like directive delimiters, these can be escaped by prefixing with a |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
diff
changeset
|
312 backslash. |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
313 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
314 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
315 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
316 \{# This *will* end up in the output, including delimiters #} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
317 This too. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
318 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
319 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
320 .. _legacy: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
321 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
322 --------------------------- |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
323 Legacy Text Template Syntax |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
324 --------------------------- |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
325 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
326 The syntax for text templates was redesigned in version 0.5 of Genshi to make |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
327 the language more flexible and powerful. The older syntax is based on line |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
328 starting with dollar signs, similar to e.g. Cheetah_ or Velocity_. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
329 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
330 .. _cheetah: http://cheetahtemplate.org/ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
331 .. _velocity: http://jakarta.apache.org/velocity/ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
332 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
333 A simple template using the old syntax looked like this: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
334 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
335 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
336 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
337 Dear $name, |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
338 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
339 We have the following items for you: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
340 #for item in items |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
341 * $item |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
342 #end |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
343 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
344 All the best, |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
345 Foobar |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
346 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
347 Beyond the requirement of putting directives on separate lines prefixed with |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
348 dollar signs, the language itself is very similar to the new one. Except that |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
349 comments are lines that start with two ``#`` characters, and a line-break at the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
350 end of a directive is removed automatically. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
351 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
352 .. note:: If you're using this old syntax, it is strongly recommended to |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
353 migrate to the new syntax. Simply replace any references to |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
354 ``TextTemplate`` by ``NewTextTemplate`` (and also change the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
355 text templates, of course). On the other hand, if you want to stick |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
356 with the old syntax for a while longer, replace references to |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
357 ``TextTemplate`` by ``OldTextTemplate``; while ``TextTemplate`` is |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
358 still an alias for the old language at this point, that will change |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
359 in a future release. But also note that the old syntax may be |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
360 dropped entirely in a future release. |