annotate doc/templates.txt @ 636:e0f12a6f3612

Follow-up to [751]: applying the optimization to text templates was actually slowing them down, so only do it for markup templates.
author cmlenz
date Wed, 05 Sep 2007 13:06:59 +0000
parents 237050080827
children 523a706d171e
rev   line source
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
2
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
3 ========================
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
4 Genshi Templating Basics
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
5 ========================
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
6
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
7 Genshi provides a template engine that can be used for generating either
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
8 markup (such as HTML_ or XML_) or plain text. While both share some of the
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
9 syntax (and much of the underlying implementation) they are essentially
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
10 separate languages.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
11
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
12 .. _html: http://www.w3.org/html/
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
13 .. _xml: http://www.w3.org/XML/
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
14
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
15 This document describes the common parts of the template engine and will be most
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
16 useful as reference to those developing Genshi templates. Templates are XML or
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
17 plain text files that include processing directives_ that affect how the
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
18 template is rendered, and template expressions_ that are dynamically substituted
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
19 by variable data.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
20
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
21
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
22 .. contents:: Contents
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
23 :depth: 3
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
24 .. sectnum::
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
25
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
26 --------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
27 Synopsis
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
28 --------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
29
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
30 A Genshi *markup template* is a well-formed XML document with embedded Python
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
31 used for control flow and variable substitution. Markup templates should be
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
32 used to generate any kind of HTML or XML output, as they provide many advantages
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
33 over simple text-based templates (such as automatic escaping of strings).
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
34
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
35 The following illustrates a very basic Genshi markup template:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
36
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
37 .. code-block:: genshi
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
38
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
39 <?python
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
40 title = "A Genshi Template"
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
41 fruits = ["apple", "orange", "kiwi"]
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
42 ?>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
43 <html xmlns:py="http://genshi.edgewall.org/">
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
44 <head>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
45 <title py:content="title">This is replaced.</title>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
46 </head>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
47
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
48 <body>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
49 <p>These are some of my favorite fruits:</p>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
50 <ul>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
51 <li py:for="fruit in fruits">
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
52 I like ${fruit}s
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
53 </li>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
54 </ul>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
55 </body>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
56 </html>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
57
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
58 This example shows:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
59
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
60 (a) a Python code block, using a processing instruction
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
61 (b) the Genshi namespace declaration
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
62 (c) usage of templates directives (``py:content`` and ``py:for``)
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
63 (d) an inline Python expression (``${fruit}``).
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
64
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
65 The template would generate output similar to this:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
66
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
67 .. code-block:: genshi
445
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
68
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
69 <html>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
70 <head>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
71 <title>A Genshi Template</title>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
72 </head>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
73
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
74 <body>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
75 <p>These are some of my favorite fruits:</p>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
76 <ul>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
77 <li>I like apples</li>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
78 <li>I like oranges</li>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
79 <li>I like kiwis</li>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
80 </ul>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
81 </body>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
82 </html>
906b346513b6 Add documentation page on the plugin API.
cmlenz
parents: 442
diff changeset
83
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
84 A *text template* is a simple plain text document that can also contain embedded
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
85 Python code. Text templates can be used to generate simple *non-markup* text
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
86 formats, such as the body of an plain text email. For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
87
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
88 .. code-block:: genshitext
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
89
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
90 Dear $name,
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
91
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
92 These are some of my favorite fruits:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
93 #for fruit in fruits
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
94 * $fruit
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
95 #end
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
96
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
97
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
98 ----------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
99 Python API
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
100 ----------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
101
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
102 The Python code required for templating with Genshi is generally based on the
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
103 following pattern:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
104
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
105 * Attain a ``MarkupTemplate`` or ``TextTemplate`` object from a string or
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
106 file-like object containing the template source. This can either be done
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
107 directly, or through a ``TemplateLoader`` instance.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
108 * Call the ``generate()`` method of the template, passing any data that should
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
109 be made available to the template as keyword arguments.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
110 * Serialize the resulting stream using its ``render()`` method.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
111
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
112 For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
113
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
114 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
115
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
116 >>> from genshi.template import MarkupTemplate
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
117 >>> tmpl = MarkupTemplate('<h1>Hello, $name!</h1>')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
118 >>> stream = tmpl.generate(name='world')
592
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
119 >>> print stream.render('xhtml')
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
120 <h1>Hello, world!</h1>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
121
592
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
122 .. note:: See the Serialization_ section of the `Markup Streams`_ page for
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
123 information on configuring template output options.
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
124
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
125 Using a text template is similar:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
126
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
127 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
128
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
129 >>> from genshi.template import TextTemplate
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
130 >>> tmpl = TextTemplate('Hello, $name!')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
131 >>> stream = tmpl.generate(name='world')
605
bc5faca93699 Text templates now default to rendering as plain text; it is no longer necessary to explicitly specify the "text" method to the `render()` or `serialize()` method of the generated markup stream. See tickets #62 and #118.
cmlenz
parents: 592
diff changeset
132 >>> print stream
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
133 Hello, world!
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
134
592
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
135 .. note:: If you want to use text templates, you should consider using the
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
136 ``NewTextTemplate`` class instead of simply ``TextTemplate``. See
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
137 the `Text Template Language`_ page.
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
138
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
139 .. _serialization: streams.html#serialization
592
7145e4eba2ec Add a new syntax for text templates, which is available alongside the old syntax for now. The new syntax is more poweful and flexible, using Django-style directive notation.
cmlenz
parents: 545
diff changeset
140 .. _`Text Template Language`: text-templates.html
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
141 .. _`Markup Streams`: streams.html
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
142
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
143 Using a template loader provides the advantage that “compiled” templates are
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
144 automatically cached, and only parsed again when the template file changes. In
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
145 addition, it enables the use of a *template search path*, allowing template
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
146 directories to be spread across different file-system locations. Using a
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
147 template loader would generally look as follows:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
148
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
149 .. code-block:: python
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
150
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
151 from genshi.template import TemplateLoader
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
152 loader = TemplateLoader([templates_dir1, templates_dir2])
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
153 tmpl = loader.load('test.html')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
154 stream = tmpl.generate(title='Hello, world!')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
155 print stream.render()
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
156
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
157 See the `API documentation <api/index.html>`_ for details on using Genshi via
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
158 the Python API.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
159
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
160
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
161 .. _`expressions`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
162
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
163 ------------------------------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
164 Template Expressions and Code Blocks
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
165 ------------------------------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
166
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
167 Python_ expressions can be used in text and directive arguments. An expression
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
168 is substituted with the result of its evaluation against the template data.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
169 Expressions in text (which includes the values of non-directive attributes) need
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
170 to prefixed with a dollar sign (``$``) and usually enclosed in curly braces
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
171 (``{…}``).
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
172
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
173 .. _python: http://www.python.org/
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
174
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
175 If the expression starts with a letter and contains only letters, digits, dots,
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
176 and underscores, the curly braces may be omitted. In all other cases, the
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
177 braces are required so that the template processor knows where the expression
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
178 ends:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
179
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
180 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
181
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
182 >>> from genshi.template import MarkupTemplate
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
183 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
184 >>> print tmpl.generate(items=['first', 'second'])
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
185 <em>First item</em>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
186
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
187 Expressions support the full power of Python. In addition, it is possible to
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
188 access items in a dictionary using “dotted notation” (i.e. as if they were
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
189 attributes), and vice-versa (i.e. access attributes as if they were items in a
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
190 dictionary):
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
191
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
192 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
193
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
194 >>> from genshi.template import MarkupTemplate
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
195 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
196 >>> print tmpl.generate(dict={'foo': 'bar'})
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
197 <em>bar</em>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
198
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
199 Because there are two ways to access either attributes or items, expressions
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
200 do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
201 rather an exception of the type ``UndefinedError``. The same kind of error is
476
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
202 raised when you try to use a top-level variable that is not in the context data.
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
203 See `Error Handling`_ below for details on how such errors are handled.
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
204
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
205
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
206 .. _`code blocks`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
207
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
208 Code Blocks
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
209 ===========
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
210
609
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
211 Templates also support full Python code blocks, using the ``<?python ?>``
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
212 processing instruction in XML templates:
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
213
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
214 .. code-block:: genshi
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
215
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
216 <div>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
217 <?python
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
218 from genshi.builder import tag
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
219 def greeting(name):
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
220 return tag.b('Hello, %s!' % name') ?>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
221 ${greeting('world')}
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
222 </div>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
223
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
224 This will produce the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
225
609
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
226 .. code-block:: xml
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
227
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
228 <div>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
229 <b>Hello, world!</b>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
230 </div>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
231
609
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
232 In text templates (although only those using the new syntax introduced in
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
233 Genshi 0.5), code blocks use the special ``{% python %}`` directive:
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
234
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
235 .. code-block:: genshitext
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
236
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
237 {% python
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
238 from genshi.builder import tag
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
239 def greeting(name):
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
240 return tag.b('Hello, %s!' % name')
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
241 %}
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
242 ${greeting('world')}
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
243
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
244 This will produce the following output::
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
245
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
246 Hello, world!
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
247
237050080827 Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents: 606
diff changeset
248
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
249 Code blocks can import modules, define classes and functions, and basically do
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
250 anything you can do in normal Python code. What code blocks can *not* do is to
606
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
251 produce content that is emitted directly tp the generated output.
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
252
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
253 .. note:: Using the ``print`` statement will print to the standard output
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
254 stream, just as it does for other Python code in your application.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
255
476
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
256 Unlike expressions, Python code in ``<?python ?>`` processing instructions can
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
257 not use item and attribute access in an interchangeable manner. That means that
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
258 “dotted notation” is always attribute access, and vice-versa.
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
259
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
260 The support for Python code blocks in templates is not supposed to encourage
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
261 mixing application code into templates, which is generally considered bad
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
262 design. If you're using many code blocks, that may be a sign that you should
081c70ff7acd Update documentation to reflect changes in [573].
cmlenz
parents: 445
diff changeset
263 move such code into separate Python modules.
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
264
545
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
265 If you'd rather not allow the use of Python code blocks in templates, you can
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
266 simply set the ``allow_exec`` parameter (available on the ``Template`` and the
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
267 ``TemplateLoader`` initializers) to ``False``. In that case Genshi will raise
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
268 a syntax error when a ``<?python ?>`` processing instruction is encountered.
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
269 But please note that disallowing code blocks in templates does not turn Genshi
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
270 into a sandboxable template engine; there are sufficient ways to do harm even
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
271 using plain expressions.
6e21c89d9255 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 510
diff changeset
272
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
273
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
274 .. _`error handling`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
275
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
276 Error Handling
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
277 ==============
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
278
606
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
279 By default, Genshi raises an ``UndefinedError`` if a template expression
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
280 attempts to access a variable that is not defined:
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
281
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
282 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
283
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
284 >>> from genshi.template import MarkupTemplate
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
285 >>> tmpl = MarkupTemplate('<p>${doh}</p>')
606
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
286 >>> tmpl.generate().render('xhtml')
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
287 Traceback (most recent call last):
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
288 ...
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
289 UndefinedError: "doh" not defined
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
290
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
291 You can change this behavior by setting the variable lookup mode to "lenient".
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
292 In that case, accessing undefined variables returns an `Undefined` object,
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
293 meaning that the expression does not fail immediately. See below for details.
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
294
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
295 If you need to check whether a variable exists in the template context, use the
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
296 defined_ or the value_of_ function described below. To check for existence of
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
297 attributes on an object, or keys in a dictionary, use the ``hasattr()``,
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
298 ``getattr()`` or ``get()`` functions, or the ``in`` operator, just as you would
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
299 in regular Python code:
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
300
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
301 >>> from genshi.template import MarkupTemplate
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
302 >>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>')
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
303 >>> print tmpl.generate().render('xhtml')
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
304 <p>False</p>
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
305
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
306 .. note:: Lenient error handling was the default in Genshi prior to version 0.5.
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
307 Strict mode was introduced in version 0.4, and became the default in
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
308 0.5. The reason for this change was that the lenient error handling
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
309 was masking actual errors in templates, thereby also making it harder
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
310 to debug some problems.
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
311
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
312
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
313 .. _`lenient`:
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
314
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
315 Lenient Mode
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
316 ------------
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
317
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
318 If you instruct Genshi to use the lenient variable lookup mode, it allows you
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
319 to access variables that are not defined, without raising an ``UndefinedError``.
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
320
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
321 This mode can be chosen by passing the ``lookup='lenient'`` keyword argument to
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
322 the template initializer, or by passing the ``variable_lookup='lenient'``
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
323 keyword argument to the ``TemplateLoader`` initializer:
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
324
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
325 .. code-block:: pycon
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
326
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
327 >>> from genshi.template import MarkupTemplate
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
328 >>> tmpl = MarkupTemplate('<p>${doh}</p>', lookup='lenient')
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
329 >>> print tmpl.generate().render('xhtml')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
330 <p></p>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
331
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
332 You *will* however get an exception if you try to call an undefined variable, or
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
333 do anything else with it, such as accessing its attributes:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
334
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
335 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
336
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
337 >>> from genshi.template import MarkupTemplate
606
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
338 >>> tmpl = MarkupTemplate('<p>${doh.oops}</p>', lookup='lenient')
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
339 >>> print tmpl.generate().render('xhtml')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
340 Traceback (most recent call last):
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
341 ...
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
342 UndefinedError: "doh" not defined
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
343
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
344 If you need to know whether a variable is defined, you can check its type
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
345 against the ``Undefined`` class, for example in a conditional directive:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
346
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 476
diff changeset
347 .. code-block:: pycon
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
348
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
349 >>> from genshi.template import MarkupTemplate
606
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
350 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</p>',
9ada030ad986 Changed the default error handling mode to "strict".
cmlenz
parents: 605
diff changeset
351 ... lookup='lenient')
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
352 >>> print tmpl.generate().render('xhtml')
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
353 <p>False</p>
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
354
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
355 Alternatively, the built-in functions defined_ or value_of_ can be used in this
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
356 case.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
357
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
358 Custom Modes
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
359 ------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
360
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
361 In addition to the built-in "lenient" and "strict" modes, it is also possible to
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
362 use a custom error handling mode. For example, you could use lenient error
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
363 handling in a production environment, while also logging a warning when an
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
364 undefined variable is referenced.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
365
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
366 See the API documentation of the ``genshi.template.eval`` module for details.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
367
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
368
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
369 Built-in Functions & Types
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
370 ==========================
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
371
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
372 The following functions and types are available by default in template code, in
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
373 addition to the standard built-ins that are available to all Python code.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
374
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
375 .. _`defined`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
376
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
377 ``defined(name)``
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
378 -----------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
379 This function determines whether a variable of the specified name exists in
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
380 the context data, and returns ``True`` if it does.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
381
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
382 .. _`value_of`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
383
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
384 ``value_of(name, default=None)``
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
385 --------------------------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
386 This function returns the value of the variable with the specified name if
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
387 such a variable is defined, and returns the value of the ``default``
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
388 parameter if no such variable is defined.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
389
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
390 .. _`Markup`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
391
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
392 ``Markup(text)``
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
393 ----------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
394 The ``Markup`` type marks a given string as being safe for inclusion in markup,
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
395 meaning it will *not* be escaped in the serialization stage. Use this with care,
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
396 as not escaping a user-provided string may allow malicious users to open your
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
397 web site to cross-site scripting attacks.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
398
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
399 .. _`Undefined`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
400
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
401 ``Undefined``
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
402 ----------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
403 The ``Undefined`` type can be used to check whether a reference variable is
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
404 defined, as explained in `error handling`_.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
405
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
406
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
407 .. _`directives`:
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
408
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
409 -------------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
410 Template Directives
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
411 -------------------
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
412
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
413 Directives provide control flow functionality for templates, such as conditions
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
414 or iteration. As the syntax for directives depends on whether you're using
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
415 markup or text templates, refer to the
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
416 `XML Template Language <xml-templates.html>`_ or
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff changeset
417 `Text Template Language <text-templates.html>`_ pages for information.
Copyright (C) 2012-2017 Edgewall Software