1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
Kajiki Templating Basics
=================================
Kajiki provides two templating engines, one which is useful for generating
markup (HTML or XML most likely), and one of which is useful for generating
plain text. This document describes the aspects of the two engines that are
similar and the basic API for using them.
Synopsis
--------------
A Kajiki *xml template* is a well-formed XML document that may include one or
more custom tags and attributes prefixed by the namespace 'py:'. XML templates
also may contain python expressions that will be evaluated at template expansion
time as well as processing instructions that may contain Python code. XML
templates should be used when generating XML or HTML, as they provide awareness
of well-formedness rules and proper escaping.
The following is an example of a simple Kajki markup template:
.. code-block:: xml
<?python
title = "A Kajiki Template"
fruits = ["apple", "orange", "kiwi"]
?>
<html>
<head>
<title py:content="title">This is replaced.</title>
</head>
<body>
<p>These are some of my favorite fruits:</p>
<ul>
<li py:for="fruit in fruits">
I like ${fruit}s
</li>
</ul>
</body>
</html>
This template would generate output similar to this (in X(H)ML mode):
.. code-block:: xml
<html>
<head>
<title>A Kajiki Template</title>
</head>
<body>
<p>These are some of my favorite fruits:</p>
<ul>
<li>I like apples</li>
<li>I like oranges</li>
<li>I like kiwis</li>
</ul>
</body>
</html>
or this (in HTML mode):
.. code-block:: html
<html>
<head>
<title>A Kajiki Template</title>
<body>
<p>These are some of my favorite fruits:
<ul>
<li>I like apples
<li>I like oranges
<li>I like kiwis
</ul>
*Text templates*, on the other hand, are plain text documents that can contain
embedded Python directives and expressions. Text templates should be used when
generating non-markup text format such as email. Here is a simple text template:
.. code-block:: none
Dear $name,
These are some of my favorite fruits:
%for fruit in fruts
* $fruit
%end
This would generate something similar to the following:
.. code-block:: none
Dear Rick,
These are some of my favorite fruits:
* Apples
* Bananas
* Pears
Python API
-------------------------
In order to actually use Kajiki in generating text (either via the XML or the
text-based languages), the pattern is as follows:
#. Obtain an XMLTemplate or TextTemplate subclass containing the template source. This can either be done directly or via a template loader.
#. Instantiate the template with one constructor argument, a dict containing all the values that should be made available as global variables to the template.
#. Render the template instance using its render() method (for rendering to a single string) or iterating through it (for "stream") rendering.
For instance:
>>> import kajiki
>>> Template = kajiki.XMLTemplate('<h1>Hello, $name!</h1>')
>>> t = Template(dict(name='world'))
>>> t.render()
'<h1>Hello, world!</h1>'
Using text templates is similar:
>>> Template = kajiki.TextTemplate('Hello, $name!')
>>> t = Template(dict(name='world'))
>>> t.render()
'Hello, world!'
You can also use a template loader to indirectly generate the template classes.
Using a template loader gives two main advantages over directly instantiating
templates:
* Compiled templates are cached and only re-parsed when the template changes.
* Several template tags such as `extends`, `import`, and `include` that require knowledge of other templates become enabled.
Using a template loader would look similar to the following::
loader = PackageLoader()
Template = loader.import_('my.package.text.template')
t = Template(dict(title='Hello, world!')
print t.render()
Template Expressions and Code Blocks
-------------------------------------------------------
Python expressions can be used in "plain text" areas of templates, including, in
XML templates, tag attributes. They are also used in some directive arguments.
Whenever a Python expression is used in a "plain text" area, it must be prefixed
by a dollar sign ($) and possibly enclosed in curly braces. If the expression
starts with a letter and contains only letters, digits, dots, and underscores,
then the curly braces may be omitted. In all other cases, they are required.
For example:
>>> Template = kajiki.XMLTemplate('<em>${items[0].capitalize()}</em>')
>>> Template(dict(items=['first', 'second'])).render()
'<em>First</em>'
>>> import sys
>>> Template = kajiki.TextTemplate('Maxint is $sys.maxsize')
>>> Template(dict(sys=sys)).render()
'Maxint is 9223372036854775807'
Escaping
^^^^^^^^^^^^^^
If you need a literal dollar sign where Kajiki would normally detect an
expression, you can simply double the dollar sign:
>>> Template = kajiki.XMLTemplate('<em>$foo</em>')
>>> Template().render()
Traceback (most recent call last):
...
NameError: global name 'foo' is not defined
>>> Template = kajiki.XMLTemplate('<em>$$foo</em>')
>>> Template().render()
'<em>$foo</em>'
Code Blocks
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Templates also support full Python syntax, using the <?py ?> processing
instruction:
.. code-block:: xml
<div>
<?py import sys>
Maxint is $sys.maxint
</div>
This will produce the following output:
.. code-block:: xml
<div>
Maxint is 9223372036854775807
</div>
In text blocks, the %py (or {%py%} directive accomplishes the same goal:
.. code-block:: none
%py import sys
Maxint is $sys.maxint
This will produce:
.. code-block:: none
Maxint is 9223372036854775807
In both of the above cases, the Python code runs in the 'local scope' of the
template's main rendering function, so any variables defined there will not be
accessible in functions or blocks defined elsewhere in the template. To force
the python block to run at 'module-level' in XML templates, simply prefix the
first line of the Python with a percent (%) sign:
>>> Template = kajiki.XMLTemplate('''<div
... ><?py %import os
... ?><py:def function="test()"
... >${os.path.join('a', 'b', 'c')}</py:def
... >${test()}</div>''')
>>> Template().render()
'<div>a/b/c</div>'
In text templates, replace the %py directive with %py%:
>>> Template = kajiki.TextTemplate('''%py% import os
... %def test()
... ${os.path.join('a','b','c')}\\
... %end
... ${test()}''')
>>> Template().render()
'a/b/c'
Built-in Functions and Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All templates have access to the following functions and variables:
.. function:: literal(x)
Wrap some user-generated text so that it doesn't get escaped along with
everything else.
.. data:: local
The current template being defined
.. data:: self
The current template being defined, or, if used in the context of a parent
template that is being extended, the final ("child-most") template in the
inheritance hierarchy.
.. data:: parent
The parent template (via py:extends) of the template being defined
.. data:: child
The child template (via py:extends) of the template being defined
Template Directives
--------------------------------------------
Template directives provide control flow and inheritance functionality for
templates. As their syntax depends on whether you're using XML or text
templates, please refer to :doc:`xml-templates` or :doc:`text-templates`
for more information.
|
