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
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Using Jinja | Jinja Documentation</title>
<style text="text/css">
body {
font-family: 'Arial', sans-serif;
margin: 1em;
padding: 0;
}
#navigation {
float: right;
margin: -1em -1em 1em 1em;
padding: 1em 2em 0 2em;
border: 1px solid #bbb;
border-width: 0 0 1px 1px;
background-color: #f8f8f8;
}
#page {
width: 45em;
}
a {
color: #d00;
}
a:hover {
color: #d40;
}
h1 {
font-size: 2em;
color: #d00;
margin: 0.5em 0 0.5em 0;
padding: 0;
}
h2 {
font-size: 1.7em;
color: #bd2121;
margin: 1em 0 0.5em 0;
}
h3 {
font-size: 1.3em;
color: #8a2424;
margin: 0.5em 0 0 0;
}
p {
margin: 0.5em 1em 0.5em 1em;
}
pre {
margin: 1em 0 1em 2em;
padding: 0.5em;
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
background-color: #f2f2f2;
overflow: auto;
}
li {
line-height: 1.4em;
}
hr {
margin: 1em;
padding: 0;
height: 1px!important;
background-color: #ccc;
border: none!important;
}
div.admonition {
margin: 1em 0 1em 1.5em;
padding: 0.5em 0.5em 0.5em 2em;
background-color: #f6e3e3;
border: 1px solid #d50000;
border-left: none;
border-right: none;
}
div.admonition p.admonition-title {
font-size: 1.1em;
color: #d40;
font-weight: bold;
margin: 0 0 0.5em -1em;
}
table {
border-collapse: collapse;
margin: 1em 2em 1em 1.5em;
}
table td, table th {
text-align: left;
border: 1px solid #eee;
padding: 0.3em;
}
table th {
background-color: #d00000;
color: white;
border: 1px solid #d00000;
border-bottom: 1px solid #eee;
}
</style>
</head>
<body>
<div id="navigation">
<h3>Documentation</h3>
<ul>
<li><a href="index.html">back to index</a></li>
<li><a href="http://wsgiarea.pocoo.org/repos/jinja/trunk/docs/source/basics-dev.txt">view source online</a></li>
</ul>
<h3>Table of Contents</h3>
<ul>
<li><a href="#loaders">Loaders</a></li>
<li><a href="#filesystemloader">FileSystemLoader</a></li>
<li><a href="#cachedfilesystemloader">CachedFileSystemLoader</a></li>
<li><a href="#eggloader">EggLoader</a></li>
<li><a href="#choiceloader">ChoiceLoader</a></li>
<li><a href="#stringloader">StringLoader</a></li>
<li><a href="#unicode-support">Unicode Support</a></li>
<li><a href="#the-template">The template</a></li>
<li><a href="#the-context">The context</a></li>
</ul>
</div>
<h1>Using Jinja</h1>
<div id="page">
<p>Using Jinja in the application side is very basic. All you have to do
is to import the <tt class="docutils literal"><span class="pre">Template</span></tt> and <tt class="docutils literal"><span class="pre">Context</span></tt> class. Additionally you
need a loader which handles the template imports:</p>
<pre class="literal-block">
from jinja import Template, Context, FileSystemLoader
t = Template('templatename', FileSystemLoader('path/to/the/templates'))
c = Context({
'users': [
{'name': 'someone', 'id': 1, 'visible': True},
{'name': 'notme', 'id': 2, 'visible': True},
{'name': 'peter', 'id': 3, 'visible': False}
]
})
print t.render(c)
</pre>
<p>The template <tt class="docutils literal"><span class="pre">templatename.html</span></tt> in <tt class="docutils literal"><span class="pre">path/to/the/templates</span></tt> might look
like this:</p>
<pre class="literal-block">
<ul id="userlist">
{% for user in users %}
{% if user.visible %}
{% define shown true %}
<li><a href="/users/{{ user.id }}/">{{ user.name|escapexml }}</a></li>
{% endif %}
{% endfor %}
{% if not shown %}
<li><strong>no users found</strong></li>
{% endif %}
</ul>
</pre>
<div class="section">
<h2><a id="loaders" name="loaders">Loaders</a></h2>
<p>There are three loaders shipped with Jinja:</p>
<div class="section">
<h3><a id="filesystemloader" name="filesystemloader">FileSystemLoader</a></h3>
<p>Create it with:</p>
<pre class="literal-block">
loader = FileSystemLoader('searchpath/')
</pre>
<p>This loader will look for templates named <tt class="docutils literal"><span class="pre">NAME.html</span></tt> and doesn't cache anything.</p>
</div>
<div class="section">
<h3><a id="cachedfilesystemloader" name="cachedfilesystemloader">CachedFileSystemLoader</a></h3>
<p>Create this loader using:</p>
<pre class="literal-block">
loader = CachedFileSystemLoader('searchpath/'[, 'cachedir/'])
</pre>
<p>Works like the <tt class="docutils literal"><span class="pre">FileSystemLoader</span></tt> but caches the reparsed nodelist in the cachdir.
If cachedir is not given it will cache it in the searchpath but with a "." prefix.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">Please notice that cached templates are much faster then reparsing them each
request because Jinja will save the preparsed nodelist in a dump.</p>
</div>
</div>
<div class="section">
<h3><a id="eggloader" name="eggloader">EggLoader</a></h3>
<p>Since jinja 0.8 you can load templates out of eggs:</p>
<pre class="literal-block">
loader = EggLoader('NameOfMyEgg', 'internal/path/to/templates')
</pre>
</div>
<div class="section">
<h3><a id="choiceloader" name="choiceloader">ChoiceLoader</a></h3>
<p>Takes a number of loader instances.</p>
<p>The <tt class="docutils literal"><span class="pre">load</span></tt> and <tt class="docutils literal"><span class="pre">load_and_compile</span></tt> method try to to call the
functions of all given loaders:</p>
<pre class="literal-block">
from jinja import ChoiceLoader, FileSystemLoader, EggLoader
loader = ChoiceLoader(
FileSystemLoader('/path/to/my/templates'),
EggLoader('MyEgg', 'internal/path/to/templates')
)
</pre>
</div>
<div class="section">
<h3><a id="stringloader" name="stringloader">StringLoader</a></h3>
<p>The <tt class="docutils literal"><span class="pre">StringLoader</span></tt> is a very basic loader without support for template inheritance,
but allows the loading of templates stored in a string:</p>
<pre class="literal-block">
template = '''{{ "Hello World" }}'''
print Template(template, StringLoader())
</pre>
<p>If you want to create your own loader check out the <a class="reference" href="./loader-dev.html">loader development</a>
document.</p>
</div>
</div>
<div class="section">
<h2><a id="unicode-support" name="unicode-support">Unicode Support</a></h2>
<p>Jinja comes with built-in Unicode support. As a matter of fact, the return
value of <tt class="docutils literal"><span class="pre">Template.render()</span></tt> will be a Python unicode object.</p>
<p>Unfortunately, most text is still stored in some form of encoding, so normal
strings must be converted to Unicode.</p>
<div class="section">
<h3><a id="the-template" name="the-template">The template</a></h3>
<p>Each template loader can be given a <tt class="docutils literal"><span class="pre">charset</span></tt> argument which defaults to
<tt class="docutils literal"><span class="pre">"utf-8"</span></tt>:</p>
<pre class="literal-block">
loader = FileSystemLoader('path', charset='latin-1')
</pre>
<p>This tells the loader that all templates it processes are encoded in the
<tt class="docutils literal"><span class="pre">latin-1</span></tt> encoding.</p>
<p>The string loader of course doesn't use the <tt class="docutils literal"><span class="pre">charset</span></tt> if you "load" Unicode
strings.</p>
</div>
<div class="section">
<h3><a id="the-context" name="the-context">The context</a></h3>
<p>Every string that is stored in your context (whether directly or tucked away in
a list or dict) and used in the template will eventually have to be converted to
Unicode too. Therefore, the context, too, takes a <tt class="docutils literal"><span class="pre">charset</span></tt> argument (which
again defaults to <tt class="docutils literal"><span class="pre">"utf-8"</span></tt>):</p>
<pre class="literal-block">
context = Context({'thing': 'Käse'}, charset='latin-1')
template.render(context)
</pre>
<p>Unicode strings in the context are not concerned as they needn't be converted.</p>
<p>You can only specify one encoding per context, so if you have strings that use
another charset you have two options:</p>
<ul>
<li><p class="first">convert them to unicode before putting them into the context</p>
</li>
<li><p class="first">put them into the context as normal strings and use the <tt class="docutils literal"><span class="pre">decode</span></tt> filter:</p>
<pre class="literal-block">
{{ russianstring | decode "koi8-r" }}
</pre>
</li>
</ul>
<p>When it encounters an encoding issue, Jinja will raise the
<tt class="docutils literal"><span class="pre">TemplateCharsetError</span></tt> exception.</p>
</div>
</div>
</div>
</body>
</html>
|
