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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Templates — Flask 0.8 documentation</title>
<link rel="stylesheet" href="_static/flasky.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.8',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Flask 0.8 documentation" href="index.html" />
<link rel="next" title="Testing Flask Applications" href="testing.html" />
<link rel="prev" title="Bonus: Testing the Application" href="tutorial/testing.html" />
<link rel="apple-touch-icon" href="_static/touch-icon.png" />
<link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="testing.html" title="Testing Flask Applications"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tutorial/testing.html" title="Bonus: Testing the Application"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Flask 0.8 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="templates">
<h1>Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h1>
<p>Flask leverages Jinja2 as template engine. You are obviously free to use
a different template engine, but you still have to install Jinja2 to run
Flask itself. This requirement is necessary to enable rich extensions.
An extension can depend on Jinja2 being present.</p>
<p>This section only gives a very quick introduction into how Jinja2
is integrated into Flask. If you want information on the template
engine’s syntax itself, head over to the official <a class="reference external" href="http://jinja.pocoo.org/2/documentation/templates">Jinja2 Template
Documentation</a> for
more information.</p>
<div class="section" id="jinja-setup">
<h2>Jinja Setup<a class="headerlink" href="#jinja-setup" title="Permalink to this headline">¶</a></h2>
<p>Unless customized, Jinja2 is configured by Flask as follows:</p>
<ul class="simple">
<li>autoescaping is enabled for all templates ending in <tt class="docutils literal"><span class="pre">.html</span></tt>,
<tt class="docutils literal"><span class="pre">.htm</span></tt>, <tt class="docutils literal"><span class="pre">.xml</span></tt> as well as <tt class="docutils literal"><span class="pre">.xhtml</span></tt></li>
<li>a template has the ability to opt in/out autoescaping with the
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">autoescape</span> <span class="pre">%}</span></tt> tag.</li>
<li>Flask inserts a couple of global functions and helpers into the
Jinja2 context, additionally to the values that are present by
default.</li>
</ul>
</div>
<div class="section" id="standard-context">
<h2>Standard Context<a class="headerlink" href="#standard-context" title="Permalink to this headline">¶</a></h2>
<p>The following global variables are available within Jinja2 templates
by default:</p>
<dl class="data">
<dt>
<tt class="descname">config</tt></dt>
<dd><p>The current configuration object (<tt class="xref py py-data docutils literal"><span class="pre">flask.config</span></tt>)</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="data">
<dt>
<tt class="descname">request</tt></dt>
<dd><p>The current request object (<a class="reference internal" href="api.html#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">flask.request</span></tt></a>)</p>
</dd></dl>
<dl class="data">
<dt>
<tt class="descname">session</tt></dt>
<dd><p>The current session object (<a class="reference internal" href="api.html#flask.session" title="flask.session"><tt class="xref py py-class docutils literal"><span class="pre">flask.session</span></tt></a>)</p>
</dd></dl>
<dl class="data">
<dt>
<tt class="descname">g</tt></dt>
<dd><p>The request-bound object for global variables (<a class="reference internal" href="api.html#flask.g" title="flask.g"><tt class="xref py py-data docutils literal"><span class="pre">flask.g</span></tt></a>)</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">url_for</tt><big>(</big><big>)</big></dt>
<dd><p>The <a class="reference internal" href="api.html#flask.url_for" title="flask.url_for"><tt class="xref py py-func docutils literal"><span class="pre">flask.url_for()</span></tt></a> function.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">get_flashed_messages</tt><big>(</big><big>)</big></dt>
<dd><p>The <a class="reference internal" href="api.html#flask.get_flashed_messages" title="flask.get_flashed_messages"><tt class="xref py py-func docutils literal"><span class="pre">flask.get_flashed_messages()</span></tt></a> function.</p>
</dd></dl>
<div class="admonition-the-jinja-context-behaviour admonition ">
<p class="first admonition-title">The Jinja Context Behaviour</p>
<p>These variables are added to the context of variables, they are not
global variables. The difference is that by default these will not
show up in the context of imported templates. This is partially caused
by performance considerations, partially to keep things explicit.</p>
<p>What does this mean for you? If you have a macro you want to import,
that needs to access the request object you have two possibilities:</p>
<ol class="arabic simple">
<li>you explicitly pass the request to the macro as parameter, or
the attribute of the request object you are interested in.</li>
<li>you import the macro “with context”.</li>
</ol>
<p>Importing with context looks like this:</p>
<div class="last highlight-jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">from</span> <span class="s1">'_helpers.html'</span> <span class="k">import</span> <span class="nv">my_macro</span> <span class="k">with context</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="standard-filters">
<h2>Standard Filters<a class="headerlink" href="#standard-filters" title="Permalink to this headline">¶</a></h2>
<p>These filters are available in Jinja2 additionally to the filters provided
by Jinja2 itself:</p>
<dl class="function">
<dt>
<tt class="descname">tojson</tt><big>(</big><big>)</big></dt>
<dd><p>This function converts the given object into JSON representation. This
is for example very helpful if you try to generate JavaScript on the
fly.</p>
<p>Note that inside <cite>script</cite> tags no escaping must take place, so make
sure to disable escaping with <tt class="docutils literal"><span class="pre">|safe</span></tt> if you intend to use it inside
<cite>script</cite> tags:</p>
<div class="highlight-html+jinja"><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">text/javascript</span><span class="nt">></span>
<span class="nx">doSomethingWith</span><span class="p">(</span><span class="cp">{{</span> <span class="nv">user.username</span><span class="o">|</span><span class="nf">tojson</span><span class="o">|</span><span class="nf">safe</span> <span class="cp">}}</span><span class="p">);</span>
<span class="nt"></script></span>
</pre></div>
</div>
<p>That the <tt class="docutils literal"><span class="pre">|tojson</span></tt> filter escapes forward slashes properly for you.</p>
</dd></dl>
</div>
<div class="section" id="controlling-autoescaping">
<h2>Controlling Autoescaping<a class="headerlink" href="#controlling-autoescaping" title="Permalink to this headline">¶</a></h2>
<p>Autoescaping is the concept of automatically escaping special characters
of you. Special characters in the sense of HTML (or XML, and thus XHTML)
are <tt class="docutils literal"><span class="pre">&</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">"</span></tt> as well as <tt class="docutils literal"><span class="pre">'</span></tt>. Because these characters
carry specific meanings in documents on their own you have to replace them
by so called “entities” if you want to use them for text. Not doing so
would not only cause user frustration by the inability to use these
characters in text, but can also lead to security problems. (see
<a class="reference internal" href="security.html#xss"><em>Cross-Site Scripting (XSS)</em></a>)</p>
<p>Sometimes however you will need to disable autoescaping in templates.
This can be the case if you want to explicitly inject HTML into pages, for
example if they come from a system that generate secure HTML like a
markdown to HTML converter.</p>
<p>There are three ways to accomplish that:</p>
<ul class="simple">
<li>In the Python code, wrap the HTML string in a <a class="reference internal" href="api.html#flask.Markup" title="flask.Markup"><tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt></a>
object before passing it to the template. This is in general the
recommended way.</li>
<li>Inside the template, use the <tt class="docutils literal"><span class="pre">|safe</span></tt> filter to explicitly mark a
string as safe HTML (<tt class="docutils literal"><span class="pre">{{</span> <span class="pre">myvariable|safe</span> <span class="pre">}}</span></tt>)</li>
<li>Temporarily disable the autoescape system altogether.</li>
</ul>
<p>To disable the autoescape system in templates, you can use the <tt class="docutils literal"><span class="pre">{%</span>
<span class="pre">autoescape</span> <span class="pre">%}</span></tt> block:</p>
<div class="highlight-html+jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">autoescape</span> <span class="kp">false</span> <span class="cp">%}</span>
<span class="nt"><p></span>autoescaping is disabled here
<span class="nt"><p></span><span class="cp">{{</span> <span class="nv">will_not_be_escaped</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Whenever you do this, please be very cautious about the variables you are
using in this block.</p>
</div>
<div class="section" id="registering-filters">
<h2>Registering Filters<a class="headerlink" href="#registering-filters" title="Permalink to this headline">¶</a></h2>
<p>If you want to register your own filters in Jinja2 you have two ways to do
that. You can either put them by hand into the
<a class="reference internal" href="api.html#flask.Flask.jinja_env" title="flask.Flask.jinja_env"><tt class="xref py py-attr docutils literal"><span class="pre">jinja_env</span></tt></a> of the application or use the
<a class="reference internal" href="api.html#flask.Flask.template_filter" title="flask.Flask.template_filter"><tt class="xref py py-meth docutils literal"><span class="pre">template_filter()</span></tt></a> decorator.</p>
<p>The two following examples work the same and both reverse an object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.template_filter</span><span class="p">(</span><span class="s">'reverse'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">reverse_filter</span><span class="p">(</span><span class="n">s</span><span class="p">):</span>
<span class="k">return</span> <span class="n">s</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="k">def</span> <span class="nf">reverse_filter</span><span class="p">(</span><span class="n">s</span><span class="p">):</span>
<span class="k">return</span> <span class="n">s</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="n">app</span><span class="o">.</span><span class="n">jinja_env</span><span class="o">.</span><span class="n">filters</span><span class="p">[</span><span class="s">'reverse'</span><span class="p">]</span> <span class="o">=</span> <span class="n">reverse_filter</span>
</pre></div>
</div>
<p>In case of the decorator the argument is optional if you want to use the
function name as name of the filter.</p>
</div>
<div class="section" id="context-processors">
<h2>Context Processors<a class="headerlink" href="#context-processors" title="Permalink to this headline">¶</a></h2>
<p>To inject new variables automatically into the context of a template
context processors exist in Flask. Context processors run before the
template is rendered and have the ability to inject new values into the
template context. A context processor is a function that returns a
dictionary. The keys and values of this dictionary are then merged with
the template context:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.context_processor</span>
<span class="k">def</span> <span class="nf">inject_user</span><span class="p">():</span>
<span class="k">return</span> <span class="nb">dict</span><span class="p">(</span><span class="n">user</span><span class="o">=</span><span class="n">g</span><span class="o">.</span><span class="n">user</span><span class="p">)</span>
</pre></div>
</div>
<p>The context processor above makes a variable called <cite>user</cite> available in
the template with the value of <cite>g.user</cite>. This example is not very
interesting because <cite>g</cite> is available in templates anyways, but it gives an
idea how this works.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper"><p class="logo"><a href="index.html">
<img class="logo" src="_static/flask.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Templates</a><ul>
<li><a class="reference internal" href="#jinja-setup">Jinja Setup</a></li>
<li><a class="reference internal" href="#standard-context">Standard Context</a></li>
<li><a class="reference internal" href="#standard-filters">Standard Filters</a></li>
<li><a class="reference internal" href="#controlling-autoescaping">Controlling Autoescaping</a></li>
<li><a class="reference internal" href="#registering-filters">Registering Filters</a></li>
<li><a class="reference internal" href="#context-processors">Context Processors</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="tutorial/testing.html" title="previous chapter">Bonus: Testing the Application</a></li>
<li>Next: <a href="testing.html" title="next chapter">Testing Flask Applications</a></li>
</ul></li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/templating.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2010, Armin Ronacher.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
|
