/usr/share/doc/python-genshi-doc/html/templates.html is in python-genshi-doc 0.7-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 | <!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/">
<title>Genshi: Genshi Templating Basics</title>
<link rel="stylesheet" href="common/style/edgewall.css" type="text/css">
</head>
<body>
<div class="document" id="genshi-templating-basics">
<div id="navigation">
<span class="projinfo">Genshi 0.7</span>
<a href="index.html">Documentation Index</a>
</div>
<h1 class="title">Genshi Templating Basics</h1>
<p>Genshi provides a template engine that can be used for generating either
markup (such as <a class="reference external" href="http://www.w3.org/html/">HTML</a> or <a class="reference external" href="http://www.w3.org/XML/">XML</a>) or plain text. While both share some of the
syntax (and much of the underlying implementation) they are essentially
separate languages.</p>
<p>This document describes the common parts of the template engine and will be most
useful as reference to those developing Genshi templates. Templates are XML or
plain text files that include processing <a class="reference internal" href="#directives">directives</a> that affect how the
template is rendered, and template <a class="reference internal" href="#expressions">expressions</a> that are dynamically substituted
by variable data.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#synopsis" id="id5">1 Synopsis</a></li>
<li><a class="reference internal" href="#python-api" id="id6">2 Python API</a></li>
<li><a class="reference internal" href="#template-expressions-and-code-blocks" id="id7">3 Template Expressions and Code Blocks</a><ul class="auto-toc">
<li><a class="reference internal" href="#escaping" id="id8">3.1 Escaping</a></li>
<li><a class="reference internal" href="#id1" id="id9">3.2 Code Blocks</a></li>
<li><a class="reference internal" href="#id2" id="id10">3.3 Error Handling</a><ul class="auto-toc">
<li><a class="reference internal" href="#lenient-mode" id="id11">3.3.1 Lenient Mode</a></li>
<li><a class="reference internal" href="#custom-modes" id="id12">3.3.2 Custom Modes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#built-in-functions-types" id="id13">3.4 Built-in Functions & Types</a><ul class="auto-toc">
<li><a class="reference internal" href="#defined-name" id="id14">3.4.1 <tt class="docutils literal">defined(name)</tt></a></li>
<li><a class="reference internal" href="#value-of-name-default-none" id="id15">3.4.2 <tt class="docutils literal">value_of(name, default=None)</tt></a></li>
<li><a class="reference internal" href="#markup-text" id="id16">3.4.3 <tt class="docutils literal">Markup(text)</tt></a></li>
<li><a class="reference internal" href="#id3" id="id17">3.4.4 <tt class="docutils literal">Undefined</tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#template-directives" id="id18">4 Template Directives</a></li>
</ul>
</div>
<div class="section" id="synopsis">
<h1>1 Synopsis</h1>
<p>A Genshi <em>markup template</em> is a well-formed XML document with embedded Python
used for control flow and variable substitution. Markup templates should be
used to generate any kind of HTML or XML output, as they provide a number of
advantages over simple text-based templates (such as automatic escaping of
variable data).</p>
<p>The following is a simple Genshi markup template:</p>
<div class="highlight"><pre><span class="cp"><?python</span>
<span class="n">title</span> <span class="o">=</span> <span class="s">"A Genshi Template"</span>
<span class="n">fruits</span> <span class="o">=</span> <span class="p">[</span><span class="s">"apple"</span><span class="p">,</span> <span class="s">"orange"</span><span class="p">,</span> <span class="s">"kiwi"</span><span class="p">]</span>
<span class="cp">?></span>
<span class="nt"><html</span> <span class="na">xmlns:py=</span><span class="s">"http://genshi.edgewall.org/"</span><span class="nt">></span>
<span class="nt"><head></span>
<span class="nt"><title</span> <span class="na">py:content=</span><span class="s">"</span><span class="n">title</span><span class="s">"</span><span class="nt">></span>This is replaced.<span class="nt"></title></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><p></span>These are some of my favorite fruits:<span class="nt"></p></span>
<span class="nt"><ul></span>
<span class="nt"><li</span> <span class="na">py:for=</span><span class="s">"</span><span class="n">fruit</span> <span class="ow">in</span> <span class="n">fruits</span><span class="s">"</span><span class="nt">></span>
I like <span class="cp">${</span><span class="n">fruit</span><span class="cp">}</span>s
<span class="nt"></li></span>
<span class="nt"></ul></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</pre></div>
<p>This example shows:</p>
<ol class="loweralpha simple">
<li>a Python code block in a processing instruction</li>
<li>the Genshi namespace declaration</li>
<li>usage of templates directives (<tt class="docutils literal">py:content</tt> and <tt class="docutils literal">py:for</tt>)</li>
<li>an inline Python expression (<tt class="docutils literal">${fruit}</tt>).</li>
</ol>
<p>The template would generate output similar to this:</p>
<div class="highlight"><pre><span class="nt"><html></span>
<span class="nt"><head></span>
<span class="nt"><title></span>A Genshi Template<span class="nt"></title></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><p></span>These are some of my favorite fruits:<span class="nt"></p></span>
<span class="nt"><ul></span>
<span class="nt"><li></span>I like apples<span class="nt"></li></span>
<span class="nt"><li></span>I like oranges<span class="nt"></li></span>
<span class="nt"><li></span>I like kiwis<span class="nt"></li></span>
<span class="nt"></ul></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</pre></div>
<p>A <em>text template</em> is a simple plain text document that can also contain
embedded Python code. Text templates are intended to be used for simple
<em>non-markup</em> text formats, such as the body of an plain text email. For
example:</p>
<div class="highlight"><pre><span class="x">Dear </span><span class="nv">$name</span><span class="x">,</span>
<span class="x">These are some of my favorite fruits:</span>
<span class="cp">#</span><span class="k">for</span> <span class="n">fruit</span> <span class="ow">in</span> <span class="n">fruits</span><span class="x"></span>
<span class="x"> * </span><span class="nv">$fruit</span><span class="x"></span>
<span class="cp">#</span><span class="k">end</span><span class="x"></span>
</pre></div>
</div>
<div class="section" id="python-api">
<h1>2 Python API</h1>
<p>The Python code required for templating with Genshi is generally based on the
following pattern:</p>
<ul class="simple">
<li>Attain a <tt class="docutils literal">MarkupTemplate</tt> or <tt class="docutils literal">TextTemplate</tt> object from a string or
file-like object containing the template source. This can either be done
directly, or through a <tt class="docutils literal">TemplateLoader</tt> instance.</li>
<li>Call the <tt class="docutils literal">generate()</tt> method of the template, passing any data that should
be made available to the template as keyword arguments.</li>
<li>Serialize the resulting stream using its <tt class="docutils literal">render()</tt> method.</li>
</ul>
<p>For example:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<h1>Hello, $name!</h1>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">stream</span> <span class="o">=</span> <span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'world'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">stream</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'xhtml'</span><span class="p">))</span>
<span class="go"><h1>Hello, world!</h1></span>
</pre></div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">See the <a class="reference external" href="streams.html#serialization">Serialization</a> section of the <a class="reference external" href="streams.html">Markup Streams</a> page for
information on configuring template output options.</p>
</div>
<p>Using a text template is similar:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">TextTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">TextTemplate</span><span class="p">(</span><span class="s">'Hello, $name!'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">stream</span> <span class="o">=</span> <span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'world'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">stream</span><span class="p">)</span>
<span class="go">Hello, world!</span>
</pre></div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If you want to use text templates, you should consider using the
<tt class="docutils literal">NewTextTemplate</tt> class instead of simply <tt class="docutils literal">TextTemplate</tt>. See
the <a class="reference external" href="text-templates.html">Text Template Language</a> page.</p>
</div>
<p>Using a <a class="reference external" href="loader.html">template loader</a> provides the advantage that “compiled” templates are
automatically cached, and only parsed again when the template file changes. In
addition, it enables the use of a <em>template search path</em>, allowing template
directories to be spread across different file-system locations. Using a
template loader would generally look as follows:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">TemplateLoader</span>
<span class="n">loader</span> <span class="o">=</span> <span class="n">TemplateLoader</span><span class="p">([</span><span class="n">templates_dir1</span><span class="p">,</span> <span class="n">templates_dir2</span><span class="p">])</span>
<span class="n">tmpl</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="s">'test.html'</span><span class="p">)</span>
<span class="n">stream</span> <span class="o">=</span> <span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s">'Hello, world!'</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">stream</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
</pre></div>
<p>See the <a class="reference external" href="api/index.html">API documentation</a> for details on using Genshi via
the Python API.</p>
</div>
<div class="section" id="template-expressions-and-code-blocks">
<span id="expressions"></span><h1>3 Template Expressions and Code Blocks</h1>
<p><a class="reference external" href="http://www.python.org/">Python</a> expressions can be used in text and directive arguments. An expression
is substituted with the result of its evaluation against the template data.
Expressions in text (which includes the values of non-directive attributes) need
to prefixed with a dollar sign (<tt class="docutils literal">$</tt>) and usually enclosed in curly braces
(<tt class="docutils literal">{…}</tt>).</p>
<p>If the expression starts with a letter and contains only letters, digits, dots,
and underscores, the curly braces may be omitted. In all other cases, the
braces are required so that the template processor knows where the expression
ends:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<em>${items[0].capitalize()} item</em>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="n">items</span><span class="o">=</span><span class="p">[</span><span class="s">'first'</span><span class="p">,</span> <span class="s">'second'</span><span class="p">]))</span>
<span class="go"><em>First item</em></span>
</pre></div>
<p>Expressions support the full power of Python. In addition, it is possible to
access items in a dictionary using “dotted notation” (i.e. as if they were
attributes), and vice-versa (i.e. access attributes as if they were items in a
dictionary):</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<em>${dict.foo}</em>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="nb">dict</span><span class="o">=</span><span class="p">{</span><span class="s">'foo'</span><span class="p">:</span> <span class="s">'bar'</span><span class="p">}))</span>
<span class="go"><em>bar</em></span>
</pre></div>
<p>Because there are two ways to access either attributes or items, expressions
do not raise the standard <tt class="docutils literal">AttributeError</tt> or <tt class="docutils literal">IndexError</tt> exceptions, but
rather an exception of the type <tt class="docutils literal">UndefinedError</tt>. The same kind of error is
raised when you try to use a top-level variable that is not in the context data.
See <a class="reference internal" href="#error-handling">Error Handling</a> below for details on how such errors are handled.</p>
<div class="section" id="escaping">
<h2>3.1 Escaping</h2>
<p>If you need to include a literal dollar sign in the output where Genshi would
normally detect an expression, you can simply add another dollar sign:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<em>$foo</em>'</span><span class="p">)</span> <span class="c"># Wanted "$foo" as literal output</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">())</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">UndefinedError</span>: <span class="n">"foo" not defined</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<em>$$foo</em>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">())</span>
<span class="go"><em>$foo</em></span>
</pre></div>
<p>But note that this is not necessary if the characters following the dollar sign
do not qualify as an expression. For example, the following needs no escaping:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<script>$(function() {})</script>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">())</span>
<span class="go"><script>$(function() {})</script></span>
</pre></div>
<p>On the other hand, Genshi will always replace two dollar signs in text with a
single dollar sign, so you'll need to use three dollar signs to get two in the
output:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<script>$$$("div")</script>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">())</span>
<span class="go"><script>$$("div")</script></span>
</pre></div>
</div>
<div class="section" id="id1">
<span id="code-blocks"></span><h2>3.2 Code Blocks</h2>
<p>Templates also support full Python code blocks, using the <tt class="docutils literal"><span class="pre"><?python</span> <span class="pre">?></span></tt>
processing instruction in XML templates:</p>
<div class="highlight"><pre><span class="nt"><div></span>
<span class="cp"><?python</span>
<span class="kn">from</span> <span class="nn">genshi.builder</span> <span class="kn">import</span> <span class="n">tag</span>
<span class="k">def</span> <span class="nf">greeting</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="k">return</span> <span class="n">tag</span><span class="o">.</span><span class="n">b</span><span class="p">(</span><span class="s">'Hello, </span><span class="si">%s</span><span class="s">!'</span> <span class="o">%</span> <span class="n">name</span><span class="p">)</span> <span class="cp">?></span>
<span class="cp">${</span><span class="n">greeting</span><span class="p">(</span><span class="s">'world'</span><span class="p">)</span><span class="cp">}</span>
<span class="nt"></div></span>
</pre></div>
<p>This will produce the following output:</p>
<div class="highlight"><pre><span class="nt"><div></span>
<span class="nt"><b></span>Hello, world!<span class="nt"></b></span>
<span class="nt"></div></span>
</pre></div>
<p>In text templates (although only those using the new syntax introduced in
Genshi 0.5), code blocks use the special <tt class="docutils literal">{% python %}</tt> directive:</p>
<div class="highlight"><pre><span class="x">{% python</span>
<span class="x"> from genshi.builder import tag</span>
<span class="x"> def greeting(name):</span>
<span class="x"> return 'Hello, %s!' % name</span>
<span class="x">%}</span>
<span class="cp">${</span><span class="n">greeting</span><span class="p">(</span><span class="s">'world'</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
<p>This will produce the following output:</p>
<pre class="literal-block">
Hello, world!
</pre>
<p>Code blocks can import modules, define classes and functions, and basically do
anything you can do in normal Python code. What code blocks can <em>not</em> do is to
produce content that is emitted directly tp the generated output.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Using the <tt class="docutils literal">print</tt> statement will print to the standard output
stream, just as it does for other Python code in your application.</p>
</div>
<p>Unlike expressions, Python code in <tt class="docutils literal"><span class="pre"><?python</span> <span class="pre">?></span></tt> processing instructions can
not use item and attribute access in an interchangeable manner. That means that
“dotted notation” is always attribute access, and vice-versa.</p>
<p>The support for Python code blocks in templates is not supposed to encourage
mixing application code into templates, which is generally considered bad
design. If you're using many code blocks, that may be a sign that you should
move such code into separate Python modules.</p>
<p>If you'd rather not allow the use of Python code blocks in templates, you can
simply set the <tt class="docutils literal">allow_exec</tt> parameter (available on the <tt class="docutils literal">Template</tt> and the
<tt class="docutils literal">TemplateLoader</tt> initializers) to <tt class="docutils literal">False</tt>. In that case Genshi will raise
a syntax error when a <tt class="docutils literal"><span class="pre"><?python</span> <span class="pre">?></span></tt> processing instruction is encountered.
But please note that disallowing code blocks in templates does not turn Genshi
into a sandboxable template engine; there are sufficient ways to do harm even
using plain expressions.</p>
</div>
<div class="section" id="id2">
<span id="error-handling"></span><h2>3.3 Error Handling</h2>
<p>By default, Genshi raises an <tt class="docutils literal">UndefinedError</tt> if a template expression
attempts to access a variable that is not defined:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<p>${doh}</p>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'xhtml'</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">UndefinedError</span>: <span class="n">"doh" not defined</span>
</pre></div>
<p>You can change this behavior by setting the variable lookup mode to "lenient".
In that case, accessing undefined variables returns an <cite>Undefined</cite> object,
meaning that the expression does not fail immediately. See below for details.</p>
<p>If you need to check whether a variable exists in the template context, use the
<a class="reference internal" href="#defined">defined</a> or the <a class="reference internal" href="#value-of">value_of</a> function described below. To check for existence of
attributes on an object, or keys in a dictionary, use the <tt class="docutils literal">hasattr()</tt>,
<tt class="docutils literal">getattr()</tt> or <tt class="docutils literal">get()</tt> functions, or the <tt class="docutils literal">in</tt> operator, just as you would
in regular Python code:</p>
<blockquote>
<pre class="doctest-block">
>>> from genshi.template import MarkupTemplate
>>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>')
>>> print(tmpl.generate().render('xhtml'))
<p>False</p>
</pre>
</blockquote>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Lenient error handling was the default in Genshi prior to version 0.5.
Strict mode was introduced in version 0.4, and became the default in
0.5. The reason for this change was that the lenient error handling
was masking actual errors in templates, thereby also making it harder
to debug some problems.</p>
</div>
<div class="section" id="lenient-mode">
<span id="lenient"></span><h3>3.3.1 Lenient Mode</h3>
<p>If you instruct Genshi to use the lenient variable lookup mode, it allows you
to access variables that are not defined, without raising an <tt class="docutils literal">UndefinedError</tt>.</p>
<p>This mode can be chosen by passing the <tt class="docutils literal"><span class="pre">lookup='lenient'</span></tt> keyword argument to
the template initializer, or by passing the <tt class="docutils literal"><span class="pre">variable_lookup='lenient'</span></tt>
keyword argument to the <tt class="docutils literal">TemplateLoader</tt> initializer:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<p>${doh}</p>'</span><span class="p">,</span> <span class="n">lookup</span><span class="o">=</span><span class="s">'lenient'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'xhtml'</span><span class="p">))</span>
<span class="go"><p></p></span>
</pre></div>
<p>You <em>will</em> however get an exception if you try to call an undefined variable, or
do anything else with it, such as accessing its attributes:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<p>${doh.oops}</p>'</span><span class="p">,</span> <span class="n">lookup</span><span class="o">=</span><span class="s">'lenient'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'xhtml'</span><span class="p">))</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">UndefinedError</span>: <span class="n">"doh" not defined</span>
</pre></div>
<p>If you need to know whether a variable is defined, you can check its type
against the <tt class="docutils literal">Undefined</tt> class, for example in a conditional directive:</p>
<div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">MarkupTemplate</span>
<span class="gp">>>> </span><span class="n">tmpl</span> <span class="o">=</span> <span class="n">MarkupTemplate</span><span class="p">(</span><span class="s">'<p>${type(doh) is not Undefined}</p>'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">lookup</span><span class="o">=</span><span class="s">'lenient'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">tmpl</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'xhtml'</span><span class="p">))</span>
<span class="go"><p>False</p></span>
</pre></div>
<p>Alternatively, the built-in functions <a class="reference internal" href="#defined">defined</a> or <a class="reference internal" href="#value-of">value_of</a> can be used in this
case.</p>
</div>
<div class="section" id="custom-modes">
<h3>3.3.2 Custom Modes</h3>
<p>In addition to the built-in "lenient" and "strict" modes, it is also possible to
use a custom error handling mode. For example, you could use lenient error
handling in a production environment, while also logging a warning when an
undefined variable is referenced.</p>
<p>See the API documentation of the <tt class="docutils literal">genshi.template.eval</tt> module for details.</p>
</div>
</div>
<div class="section" id="built-in-functions-types">
<h2>3.4 Built-in Functions & Types</h2>
<p>The following functions and types are available by default in template code, in
addition to the standard built-ins that are available to all Python code.</p>
<div class="section" id="defined-name">
<span id="defined"></span><h3>3.4.1 <tt class="docutils literal">defined(name)</tt></h3>
<p>This function determines whether a variable of the specified name exists in
the context data, and returns <tt class="docutils literal">True</tt> if it does.</p>
</div>
<div class="section" id="value-of-name-default-none">
<span id="value-of"></span><h3>3.4.2 <tt class="docutils literal">value_of(name, default=None)</tt></h3>
<p>This function returns the value of the variable with the specified name if
such a variable is defined, and returns the value of the <tt class="docutils literal">default</tt>
parameter if no such variable is defined.</p>
</div>
<div class="section" id="markup-text">
<span id="markup"></span><h3>3.4.3 <tt class="docutils literal">Markup(text)</tt></h3>
<p>The <tt class="docutils literal">Markup</tt> type marks a given string as being safe for inclusion in markup,
meaning it will <em>not</em> be escaped in the serialization stage. Use this with care,
as not escaping a user-provided string may allow malicious users to open your
web site to cross-site scripting attacks.</p>
</div>
<div class="section" id="id3">
<span id="undefined"></span><h3>3.4.4 <tt class="docutils literal">Undefined</tt></h3>
<p>The <tt class="docutils literal">Undefined</tt> type can be used to check whether a reference variable is
defined, as explained in <a class="reference internal" href="#error-handling">error handling</a>.</p>
</div>
</div>
</div>
<div class="section" id="template-directives">
<span id="directives"></span><h1>4 Template Directives</h1>
<p>Directives provide control flow functionality for templates, such as conditions
or iteration. As the syntax for directives depends on whether you're using
markup or text templates, refer to the
<a class="reference external" href="xml-templates.html">XML Template Language</a> or
<a class="reference external" href="text-templates.html">Text Template Language</a> pages for information.</p>
</div>
<div id="footer">
Visit the Genshi open source project at
<a href="http://genshi.edgewall.org/">http://genshi.edgewall.org/</a>
</div>
</div>
</body>
</html>
|