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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Scopes and Variable Behavior — 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">Scopes and Variable Behavior</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="#scopes">Scopes</a></li>
<li><a href="#template-globals">Template Globals</a></li>
<li><a href="#undefined-variables">Undefined Variables</a></li>
<li><a href="#overriding-variables-of-outer-scopes">Overriding Variables Of Outer Scopes</a></li>
</ul>
</div>
<div id="contentwrapper">
<p>This section of the documentation covers the Jinja behavior regarding
variable visibility.</p>
<div class="section">
<h2><a id="scopes" name="scopes">Scopes</a></h2>
<p>Jinja has multiple scopes. A scope is something like a new transparent foil on
a stack of foils. You can only write to the outermost foil but read all of them
since you can look through them. If you remove the top foil all data on that
foil disappears. Some tags in Jinja add a new layer to the stack. Currently
these are <cite>block</cite>, <cite>for</cite>, <cite>macro</cite> and <cite>filter</cite>. This means that variables and
other elements defined inside a macro, loop or some of the other tags listed
above will be only available in that block. Here an example:</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">macro</span> <span class="nv">angryhello</span> <span class="nv">name</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">set</span> <span class="nv">angryname</span> <span class="o">=</span> <span class="nv">name</span><span class="o">|</span><span class="nf">upper</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> Hello </span><span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span><span class="x">. Hello </span><span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span><span class="x">!</span>
<span class="x"> HELLO </span><span class="cp">{{</span> <span class="nv">angryname</span> <span class="cp">}}</span><span class="x">!!!!!!111</span>
<span class="cp">{%</span> <span class="k">endmacro</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<p>The variable <tt class="docutils literal"><span class="pre">angryname</span></tt> just exists inside the macro, not outside it.</p>
<p>Defined macros appear on the context as variables. Because of this, they are
affected by the scoping too. A macro defined inside of a macro is just available
in those two macros (the macro itself and the macro it's defined in).</p>
</div>
<div class="section">
<h2><a id="template-globals" name="template-globals">Template Globals</a></h2>
<p>A special threatment exists for template code outside of visible blocks in
child templates. This code will be executed <strong>before</strong> the layout template
code. Thus it can be used to propagate values back to the layout template or
import macros from templates for rendering.</p>
<p>Such code can output data but it won't appear in the final rendering. So no
additional whitespace will pollute the template.</p>
<p>Because this code is executed before the actual layout template code it's
possible that the layout code overrides some of those variables. Usually
this is not a problem because of different variable names but it can be
a problem if you plan to specify default values.</p>
<p>In that case you have to test if the variable is not defined before setting
it:</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">if</span> <span class="k">not</span> <span class="nv">page_title</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">set</span> <span class="nv">page_title</span> <span class="o">=</span> <span class="s1">'Default Page Title'</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<p>You can of course also use the <cite>|default</cite> filter.</p>
<div class="admonition-explanation admonition">
<p class="first admonition-title">Explanation</p>
<p>This template stored as <cite>a.html</cite>:</p>
<div class="syntax"><pre><span class="nt"><title></span><span class="cp">{{</span> <span class="nv">title</span><span class="o">|</span><span class="nf">default</span><span class="o">(</span><span class="s1">'Untitled'</span><span class="o">)</span> <span class="cp">}}</span><span class="nt"></title></span>
<span class="nt"><body></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">body</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
<p>...and this child template stored as <cite>b.html</cite>:</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s1">'a.html'</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">include</span> <span class="s1">'macros.tmpl'</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">title</span> <span class="o">=</span> <span class="s1">'My Page'</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">body</span> <span class="cp">%}{{</span> <span class="nv">wrap</span><span class="o">(</span><span class="m">42</span><span class="o">)</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
<p>...and this code in <cite>macros.tmpl</cite>:</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">macro</span> <span class="nv">wrap</span><span class="o">(</span><span class="nv">text</span><span class="o">)</span> <span class="cp">%}</span>
[<span class="cp">{{</span> <span class="nv">text</span> <span class="cp">}}</span>]
<span class="cp">{%</span> <span class="k">endmacro</span> <span class="cp">%}</span>
</pre></div>
<p>..will translate to something with the same semantics as this (just
that the value is not stored in a variable):</p>
<div class="last"><div class="syntax"><pre><span class="cp">{%</span> <span class="k">filter</span> <span class="nf">capture</span><span class="o">(</span><span class="s1">'captured'</span><span class="o">,</span> <span class="kp">true</span><span class="o">)</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">macro</span> <span class="nv">wrap</span><span class="o">(</span><span class="nv">text</span><span class="o">)</span> <span class="cp">%}</span>
[<span class="cp">{{</span> <span class="nv">text</span> <span class="cp">}}</span>]
<span class="cp">{%</span> <span class="k">endmacro</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">title</span><span class="o">=</span><span class="s1">'My Page'</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endfilter</span> <span class="cp">%}</span>
<span class="nt"><title></span><span class="cp">{{</span> <span class="nv">title</span><span class="o">|</span><span class="nf">default</span><span class="o">(</span><span class="s1">'Untitled'</span><span class="o">)</span> <span class="cp">}}</span><span class="nt"></title></span>
<span class="nt"><body></span>
<span class="cp">{{</span> <span class="nv">wrap</span><span class="o">(</span><span class="m">42</span><span class="o">)</span> <span class="cp">}}</span>
<span class="nt"></body></span>
</pre></div>
</div></div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This implementation was improved in Jinja 1.1. In Jinja 1.0 blocks that
were not top-level were not propagated to the layout template. This made
it impossible to use conditional expressions for inclusion in non root
templates.</p>
</div>
</div>
<div class="section">
<h2><a id="undefined-variables" name="undefined-variables">Undefined Variables</a></h2>
<p>If you have already worked with python you probably know about the fact that
undefined variables raise an exception. This is different in Jinja. There is a
special value called <cite>undefined</cite> that represents values that do not exist.</p>
<p>Depending on the configuration it will behave different.</p>
<p>In order to check if a value is defined you can use the <cite>defined</cite> test:</p>
<div class="syntax"><pre><span class="cp">{{</span> <span class="nv">myvariable</span> <span class="k">is</span> <span class="k">not</span> <span class="nf">defined</span> <span class="cp">}}</span><span class="x"></span>
<span class="x"> will return true if the variable does not exist.</span>
</pre></div>
<p><cite>SilentUndefined</cite>:</p>
<blockquote>
<p>The silent <cite>undefined</cite> is the default behavior. The <cite>undefined</cite> object works
complete different from any variables you maybe know. If you print it
using <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">variable</span> <span class="pre">}}</span></tt> it will not appear because it's literally empty.
If you try to iterate over it, it will work. But no items are returned.</p>
<p>In order to check if a value is defined you can use the <cite>defined</cite> test:</p>
<p>There are also some additional rules regarding this special value. Any
mathematical operators (<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>) return the operand
as result:</p>
<div class="syntax"><pre><span class="cp">{{</span> <span class="kp">undefined</span> <span class="o">+</span> <span class="s2">"foo"</span> <span class="cp">}}</span><span class="x"></span>
<span class="x"> returns "foo"</span>
<span class="cp">{{</span> <span class="kp">undefined</span> <span class="o">-</span> <span class="m">42</span> <span class="cp">}}</span><span class="x"></span>
<span class="x"> returns 42. Note: not -42!</span>
</pre></div>
<p>In any expression <cite>undefined</cite> evaluates to <cite>false</cite>. It has no length, all
attribute calls return undefined, calling too:</p>
<div class="syntax"><pre><span class="cp">{{</span> <span class="kp">undefined</span><span class="nv">.attribute</span><span class="o">()</span><span class="nv">.attribute_too</span><span class="o">[</span><span class="m">42</span><span class="o">]</span> <span class="cp">}}</span><span class="x"></span>
<span class="x"> still returns `undefined`.</span>
</pre></div>
</blockquote>
<p><cite>ComplainingUndefined</cite>:</p>
<blockquote>
<p>Starting with Jinja 1.1 it's possible to replace the default undefined
object with different values. The other common undefined object which
comes with Jinja is the <cite>ComplainingUndefined</cite> object.</p>
<p>It raises exceptions as soon as you either render it or want to iterate
over it or try to access attributes etc.</p>
</blockquote>
</div>
<div class="section">
<h2><a id="overriding-variables-of-outer-scopes" name="overriding-variables-of-outer-scopes">Overriding Variables Of Outer Scopes</a></h2>
<p><em>New in Jinja 1.2</em></p>
<p>Normally you cannot override a variable from an outer scope, you can just hide
it. There is however a way to override a variable from an outer scope using the
<cite>set</cite> tag, postfixed with a bang (!):</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">set</span> <span class="nv">last_item</span> <span class="o">=</span> <span class="nv">none</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">item</span> <span class="k">in</span> <span class="nv">seq</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">set</span> <span class="nv">last_item</span> <span class="o">=</span> <span class="nv">item</span><span class="p">!</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<p>After the iteration <cite>last_item</cite> will point to the item of the last iteration.</p>
<p>If <cite>last_item</cite> was not defined in the outer scope it would be defined in the
outermost scope.</p>
</div>
</div>
</div>
</body>
<!-- generated on: 2007-11-17 18:18:07.626153
file id: scopes -->
</html>
|
