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
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Framework Integration — Jinja Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" href="style.css" type="text/css">
<style type="text/css">
.syntax { background: #ffffff; }
.syntax .c { color: #888888 } /* Comment */
.syntax .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.syntax .k { color: #008800; font-weight: bold } /* Keyword */
.syntax .cm { color: #888888 } /* Comment.Multiline */
.syntax .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.syntax .c1 { color: #888888 } /* Comment.Single */
.syntax .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.syntax .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.syntax .ge { font-style: italic } /* Generic.Emph */
.syntax .gr { color: #aa0000 } /* Generic.Error */
.syntax .gh { color: #303030 } /* Generic.Heading */
.syntax .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.syntax .go { color: #888888 } /* Generic.Output */
.syntax .gp { color: #555555 } /* Generic.Prompt */
.syntax .gs { font-weight: bold } /* Generic.Strong */
.syntax .gu { color: #606060 } /* Generic.Subheading */
.syntax .gt { color: #aa0000 } /* Generic.Traceback */
.syntax .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.syntax .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.syntax .kp { color: #008800 } /* Keyword.Pseudo */
.syntax .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.syntax .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.syntax .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.syntax .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.syntax .na { color: #336699 } /* Name.Attribute */
.syntax .nb { color: #003388 } /* Name.Builtin */
.syntax .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.syntax .no { color: #003366; font-weight: bold } /* Name.Constant */
.syntax .nd { color: #555555 } /* Name.Decorator */
.syntax .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.syntax .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.syntax .nl { color: #336699; font-style: italic } /* Name.Label */
.syntax .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.syntax .py { color: #336699; font-weight: bold } /* Name.Property */
.syntax .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.syntax .nv { color: #336699 } /* Name.Variable */
.syntax .ow { color: #008800 } /* Operator.Word */
.syntax .w { color: #bbbbbb } /* Text.Whitespace */
.syntax .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.syntax .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.syntax .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.syntax .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.syntax .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.syntax .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.syntax .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.syntax .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.syntax .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.syntax .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.syntax .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.syntax .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.syntax .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.syntax .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.syntax .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.syntax .bp { color: #003388 } /* Name.Builtin.Pseudo */
.syntax .vc { color: #336699 } /* Name.Variable.Class */
.syntax .vg { color: #dd7700 } /* Name.Variable.Global */
.syntax .vi { color: #3333bb } /* Name.Variable.Instance */
.syntax .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
</style>
</head>
<body>
<div id="content">
<h1 class="heading"><span>Jinja</span></h1>
<h2 class="subheading">Framework Integration</h2>
<div id="toc">
<h2>Navigation</h2>
<ul>
<li><a href="index.html">back to index</a></li>
</ul>
<h2>Contents</h2>
<ul class="contents">
<li><a href="#buffet">Buffet</a></li>
<li><a href="#general-template-interface">General Template Interface</a></li>
<li><a href="#django">Django</a></li>
</ul>
</div>
<div id="contentwrapper">
<p>Starting with Jinja 1.1 it's possible to embed Jinja into some of the existing
frameworks a lot easier. When speaking of frameworks we only refer to <a class="reference" href="http://www.pylonshq.com/">Pylons</a>
which has a working implementation of the TurboGears template specification.</p>
<p>Since the whole situation is problematic because of various reasons (kid
specific, uses dotted names for template loading, package name prefix etc.)
we worked around some of the problems by using pylons specific workarounds.</p>
<p>Jinja also ships an implementation for a hypothetical template abstraction layer
called <a class="reference" href="http://trac.pocoo.org/wiki/GeneralTemplateInterface">General Template Interface</a> which isn't implemented by any existing
framework so far. This specification however tries to solve the problems that
exist in Buffet.</p>
<div class="section">
<h2><a id="buffet" name="buffet">Buffet</a></h2>
<p>The buffet specification proposes that templates are named in dotted names. That
means <cite>foo.bar</cite> and not <cite>foo/bar.html</cite>. The dotted notation has the disadvantage
that you cannot specify the filename extension. In recent pylons versions it's
however possible to load templates with their native path too if you prefix the
template name with a foreslash (<cite>/foo/bar.html</cite>). If you don't specify the
extension it will assume <cite>.html</cite> for the dotted notation.</p>
<p>Here the list of configuration values:</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">jinja.extension</span></tt></td>
<td>The template extension when templates are loaded using
the dotted notation. Defaults to <tt class="docutils literal"><span class="pre">html</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.environment</span></tt></td>
<td>If this is provided it must be the only configuration
value and it's used as jinja environment. In that
case all other configuration parameters except of
<tt class="docutils literal"><span class="pre">jinja.extension</span></tt> are ignored.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.searchpath</span></tt></td>
<td>If provided a new file system loader with this
search path is instanciated.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.package</span></tt></td>
<td>Name of the python package containing the
templates. If this and <tt class="docutils literal"><span class="pre">package_path</span></tt> is
defined a <cite>PackageLoader</cite> is used.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.package_path</span></tt></td>
<td>Path to the templates inside of a package.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.loader_func</span></tt></td>
<td>Function that takes the name of the template to
load. If it returns a string or unicode object
it's used to load a template. If the return
value is None it's considered missing.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.getmtime_func</span></tt></td>
<td>Function used to check if templates requires
reloading. Has to return the UNIX timestamp of
the last template change or 0 if this template
does not exist or requires updates at any cost.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.use_memcache</span></tt></td>
<td>Set this to <tt class="docutils literal"><span class="pre">True</span></tt> to enable memory caching.
This is usually a good idea in production mode,
but disable it during development since it won't
reload template changes automatically.
This only works in persistent environments like
FastCGI.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.memcache_size</span></tt></td>
<td>Number of template instance you want to cache.
Defaults to <tt class="docutils literal"><span class="pre">40</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.cache_folder</span></tt></td>
<td>Set this to an existing directory to enable
caching of templates on the file system. Note
that this only affects templates transformed
into python code. Default is <tt class="docutils literal"><span class="pre">None</span></tt> which means
that caching is disabled.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">jinja.auto_reload</span></tt></td>
<td>Set this to <cite>False</cite> for a slightly better
performance. In that case of <cite>getmtime_func</cite>
not being provided this won't have an effect.</td>
</tr>
</tbody>
</table>
<p>All other options that start with <cite>jinja.</cite> are automatically forwarded to the
environment constructor.</p>
<p>In pylons for example you can use jinja as buffet plugin like this:</p>
<p>Edit the <cite>yourproject/config/middleware.py</cite> and add this to <cite>config.init_app</cite>:</p>
<div class="syntax"><pre><span class="n">config</span><span class="o">.</span><span class="n">add_template_engine</span><span class="p">(</span><span class="s">'jinja'</span><span class="p">,</span> <span class="s">''</span><span class="p">,</span> <span class="p">{</span>
<span class="s">'jinja.package'</span><span class="p">:</span> <span class="s">'yourapplication'</span><span class="p">,</span>
<span class="s">'jinja.package_path'</span><span class="p">:</span> <span class="s">'res/templates'</span><span class="p">,</span>
<span class="s">'jinja.use_memcache'</span><span class="p">:</span> <span class="bp">True</span>
<span class="p">})</span>
</pre></div>
<p>Note that it's a good idea to set the second parameter to an empty string.
It's meant to be used as replacement for the turbogears package name but
Jinja assumes that the name of the template does not include the package
path.</p>
<p>You can then render the template in the view like this:</p>
<div class="syntax"><pre><span class="k">class</span> <span class="nc">ExampleController</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">c</span><span class="o">.</span><span class="n">title</span> <span class="o">=</span> <span class="s">"Your Page"</span>
<span class="n">c</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="s">'hi'</span>
<span class="k">return</span> <span class="n">render_response</span><span class="p">(</span><span class="s">'jinja'</span><span class="p">,</span> <span class="s">'test_template'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">download</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">c</span><span class="o">.</span><span class="n">title</span> <span class="o">=</span> <span class="s">"Downloads"</span>
<span class="n">c</span><span class="o">.</span><span class="n">downloads</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1</span><span class="p">,</span> <span class="mf">2</span><span class="p">,</span> <span class="mf">3</span><span class="p">]</span>
<span class="k">return</span> <span class="n">render_response</span><span class="p">(</span><span class="s">'jinja'</span><span class="p">,</span> <span class="s">'/downloads.html'</span><span class="p">)</span>
</pre></div>
<p>With the settings from above rendering the <cite>index</cite> action will result in
rendering the template <tt class="docutils literal"><span class="pre">res/templates/test_template.html</span></tt> where res is
a folder in the <tt class="docutils literal"><span class="pre">yourapplication</span></tt> python package.</p>
<p>The <cite>downloads</cite> action uses the pylons specific leading foreslash notation.</p>
</div>
<div class="section">
<h2><a id="general-template-interface" name="general-template-interface">General Template Interface</a></h2>
<p>Because nobody implemented this specification so far it's not documented here
but in the sourcecode of the <a class="reference" href="http://trac.pocoo.org/browser/jinja/trunk/jinja/plugin.py">plugin module</a>. The specification itself is
explained on the pocoo trac on the <a class="reference" href="http://trac.pocoo.org/wiki/GeneralTemplateInterface">General Template Interface</a> wiki page.</p>
</div>
<div class="section">
<h2><a id="django" name="django">Django</a></h2>
<p>Using Jinja in django is straightforward because django has a pretty low
level response interface. Just have a look at the <a class="reference" href="./devrecipies.html">developer recipies</a>,
there are some examples for django. Starting with Jinja 1.2 there is also
a contrib module that simplifies using Jinja in an unicode enabled django.</p>
<div class="section">
<h3><a id="quickstart" name="quickstart">Quickstart</a></h3>
<p>To get started execute the following code at the bottom of your settings.py
or in some general application file such as urls.py or a central module. The
only thing that matters is that it's executed right <em>after</em> the settings
were set up and <em>before</em> <cite>django.contrib.jinja</cite> is imported:</p>
<pre class="literal-block">
from jinja.contrib import djangosupport
djangosupport.configure()
</pre>
<p>What this does is setting up a Jinja environment for this django instance
with loaders for <cite>TEMPLATE_DIRS</cite> etc. It also converts a couple of default
django filters such as <cite>date</cite> and <cite>timesince</cite> which are not available in
Jinja per default. If you want to change the list you can provide others
by passing a list with filter import names as <cite>convert_filters</cite> keyword
argument.</p>
<p>All other keyword arguments are forwarded to the environment. If you want
to provide a loader yourself pass it a loader keyword argument.</p>
</div>
<div class="section">
<h3><a id="rendering-templates" name="rendering-templates">Rendering Templates</a></h3>
<p>To render a template you can use the functions <cite>render_to_string</cite> or
<cite>render_to_response</cite> from the <cite>django.contrib.jinja</cite> module:</p>
<pre class="literal-block">
from django.contrib.jinja import render_to_response
resp = render_to_response('Hello {{ username }}!', {
'username': req.session['username']
}, req)
</pre>
<p><cite>render_to_string</cite> and <cite>render_to_response</cite> take at least the name of
the template as argument, then the optional dict which will become the
context. If you also provide a request object as third argument the
context processors will be applied.</p>
<p><cite>render_to_response</cite> also takes a forth parameter which can be the
content type which defaults to <cite>DEFAULT_CONTENT_TYPE</cite>.</p>
</div>
<div class="section">
<h3><a id="converting-filters" name="converting-filters">Converting Filters</a></h3>
<p>One of the useful objects provided by <cite>django.contrib.jinja</cite> is the
<cite>register</cite> object which can be used to register filters, tests and
global objects. You can also convert any filter django provides in
a Jinja filter using <cite>convert_django_filter</cite>:</p>
<pre class="literal-block">
from django.contrib.jinja import register, convert_django_filter
from django.template.defaultfilters import floatformat
register.filter(convert_django_filter(floatformat), 'floatformat')
</pre>
<p>Available methods on the <cite>register</cite> object:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">object</span> <span class="pre">(obj[,</span> <span class="pre">name])</span></tt></dt>
<dd>Register a new global as name or with the object's name.
Returns the function object unchanged so that you can use
it as decorator if no name is provided.</dd>
<dt><tt class="docutils literal"><span class="pre">filter</span> <span class="pre">(func[,</span> <span class="pre">name])</span></tt></dt>
<dd>Register a function as filter with the name provided or
the object's name as filtername.
Returns the function object unchanged so that you can use
it as decorator if no name is provided.</dd>
<dt><tt class="docutils literal"><span class="pre">test</span> <span class="pre">(func[,</span> <span class="pre">name])</span></tt></dt>
<dd>Register a function as test with the name provided or the
object's name as testname.
Returns the function object unchanged so that you can use
it as decorator if no name is provided.</dd>
<dt><tt class="docutils literal"><span class="pre">context_inclusion</span> <span class="pre">(func,</span> <span class="pre">template[,</span> <span class="pre">name])</span></tt></dt>
<dd><p class="first">Register a function with a name provided or the func object's
name in the global namespace that acts as subrender function.</p>
<p>func is called with the callers context as dict and the
arguments and keywords argument of the inclusion function.
The function should then process the context and return a
new context or the same context object. Afterwards the
template is rendered with this context.</p>
<p>Example:</p>
<pre class="literal-block">
def add_author(context, author=None):
if author is not None:
author = Author.objects.get(name=author)
context['author'] = author
return context
register.context_inclusion(add_author, 'author_details.html',
'render_author_details')
</pre>
<p>You can use it in the template like this then:</p>
<pre class="last literal-block">
{{ render_author_details('John Doe') }}
</pre>
</dd>
<dt><tt class="docutils literal"><span class="pre">clean_inclusion</span> <span class="pre">(func,</span> <span class="pre">template[,</span> <span class="pre">name[,</span> <span class="pre">run_processors]])</span></tt></dt>
<dd>Works like <cite>context_inclusion</cite> but doesn't use the calles
context but an empty context. If <cite>run_processors</cite> is <cite>True</cite>
it will lookup the context for a <cite>request</cite> object and pass
it to the render function to apply context processors.</dd>
</dl>
</div>
</div>
</div>
</div>
</body>
<!-- generated on: 2007-11-17 18:18:05.219220
file id: frameworks -->
</html>
|
