Mercurial > genshi > mirror
annotate doc/templates.txt @ 812:967236817c6a stable-0.5.x
Ported [1013] to 0.5.x branch.
author | cmlenz |
---|---|
date | Mon, 09 Mar 2009 09:00:00 +0000 |
parents | e162edb680cf |
children |
rev | line source |
---|---|
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 -*- |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ======================== |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ======================== |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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/ |
97544725bb7f
Back out [510] and instead implement configurable error handling 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/ |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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:: |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 -------- |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 -------- |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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). |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
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: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
36 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
37 .. code-block:: genshi |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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" |
97544725bb7f
Back out [510] and instead implement configurable error handling 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"] |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ?> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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/"> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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"> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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: |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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``) |
97544725bb7f
Back out [510] and instead implement configurable error handling 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}``). |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
65 The template would generate output similar to this: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
66 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
67 .. code-block:: genshi |
445 | 68 |
69 <html> | |
70 <head> | |
71 <title>A Genshi Template</title> | |
72 </head> | |
73 | |
74 <body> | |
75 <p>These are some of my favorite fruits:</p> | |
76 <ul> | |
77 <li>I like apples</li> | |
78 <li>I like oranges</li> | |
79 <li>I like kiwis</li> | |
80 </ul> | |
81 </body> | |
82 </html> | |
83 | |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
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: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
87 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
88 .. code-block:: genshitext |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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, |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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: |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ---------- |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ---------- |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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: |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
112 For example: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
113 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
114 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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>') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1da8de3e5e51
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
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1da8de3e5e51
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 |
1da8de3e5e51
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. |
1da8de3e5e51
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
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
125 Using a text template is similar: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
126 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
127 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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!') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
d0345c64da65
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
97544725bb7f
Back out [510] and instead implement configurable error handling 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! |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1da8de3e5e51
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 |
1da8de3e5e51
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 |
1da8de3e5e51
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
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1da8de3e5e51
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
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
147 template loader would generally look as follows: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
148 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
149 .. code-block:: python |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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]) |
97544725bb7f
Back out [510] and instead implement configurable error handling 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') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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!') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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() |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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`: |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ------------------------------------ |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ------------------------------------ |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 (``{…}``). |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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/ |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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, |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
178 ends: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
179 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
180 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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>') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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']) |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
190 dictionary): |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
191 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
192 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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>') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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'}) |
97544725bb7f
Back out [510] and instead implement configurable error handling 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> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 | 202 raised when you try to use a top-level variable that is not in the context data. |
203 See `Error Handling`_ below for details on how such errors are handled. | |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
812 | 206 Escaping |
207 ======== | |
208 | |
209 If you need to include a literal dollar sign in the output where Genshi would | |
210 normally detect an expression, you can simply add another dollar sign: | |
211 | |
212 .. code-block:: pycon | |
213 | |
214 >>> from genshi.template import MarkupTemplate | |
215 >>> tmpl = MarkupTemplate('<em>$foo</em>') # Wanted "$foo" as literal output | |
216 >>> print tmpl.generate() | |
217 Traceback (most recent call last): | |
218 ... | |
219 UndefinedError: "foo" not defined | |
220 >>> tmpl = MarkupTemplate('<em>$$foo</em>') | |
221 >>> print tmpl.generate() | |
222 <em>$foo</em> | |
223 | |
224 But note that this is not necessary if the characters following the dollar sign | |
225 do not qualify as an expression. For example, the following needs no escaping: | |
226 | |
227 .. code-block:: pycon | |
228 | |
229 >>> tmpl = MarkupTemplate('<script>$(function() {})</script>') | |
230 >>> print tmpl.generate() | |
231 <script>$(function() {})</script> | |
232 | |
233 On the other hand, Genshi will always replace two dollar signs in text with a | |
234 single dollar sign, so you'll need to use three dollar signs to get two in the | |
235 output: | |
236 | |
237 .. code-block:: pycon | |
238 | |
239 >>> tmpl = MarkupTemplate('<script>$$$("div")</script>') | |
240 >>> print tmpl.generate() | |
241 <script>$$("div")</script> | |
242 | |
243 | |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
244 .. _`code blocks`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
245 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
246 Code Blocks |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
247 =========== |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
248 |
609
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
249 Templates also support full Python code blocks, using the ``<?python ?>`` |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
250 processing instruction in XML templates: |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
251 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
252 .. code-block:: genshi |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 <div> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 <?python |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
256 from genshi.builder import tag |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
257 def greeting(name): |
649 | 258 return tag.b('Hello, %s!' % name) ?> |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
259 ${greeting('world')} |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
260 </div> |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
261 |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
262 This will produce the following output: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
263 |
609
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
264 .. code-block:: xml |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
265 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
266 <div> |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
267 <b>Hello, world!</b> |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
268 </div> |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
269 |
609
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
270 In text templates (although only those using the new syntax introduced in |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
271 Genshi 0.5), code blocks use the special ``{% python %}`` directive: |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
272 |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
273 .. code-block:: genshitext |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
274 |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
275 {% python |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
276 from genshi.builder import tag |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
277 def greeting(name): |
649 | 278 return 'Hello, %s!' % name |
609
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
279 %} |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
280 ${greeting('world')} |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
281 |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
282 This will produce the following output:: |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
283 |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
284 Hello, world! |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
285 |
6d4877844e28
Add support for Python code blocks in text templates using the new syntax.
cmlenz
parents:
606
diff
changeset
|
286 |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
287 Code blocks can import modules, define classes and functions, and basically do |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
288 anything you can do in normal Python code. What code blocks can *not* do is to |
606
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
289 produce content that is emitted directly tp the generated output. |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
290 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
291 .. note:: Using the ``print`` statement will print to the standard output |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
292 stream, just as it does for other Python code in your application. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
293 |
476 | 294 Unlike expressions, Python code in ``<?python ?>`` processing instructions can |
295 not use item and attribute access in an interchangeable manner. That means that | |
296 “dotted notation” is always attribute access, and vice-versa. | |
297 | |
298 The support for Python code blocks in templates is not supposed to encourage | |
299 mixing application code into templates, which is generally considered bad | |
300 design. If you're using many code blocks, that may be a sign that you should | |
301 move such code into separate Python modules. | |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
302 |
545
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
303 If you'd rather not allow the use of Python code blocks in templates, you can |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
304 simply set the ``allow_exec`` parameter (available on the ``Template`` and the |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
305 ``TemplateLoader`` initializers) to ``False``. In that case Genshi will raise |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
306 a syntax error when a ``<?python ?>`` processing instruction is encountered. |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
307 But please note that disallowing code blocks in templates does not turn Genshi |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
308 into a sandboxable template engine; there are sufficient ways to do harm even |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
309 using plain expressions. |
619340e2d805
Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents:
510
diff
changeset
|
310 |
692
e162edb680cf
Add warning about using code blocks on Python 2.3. Closes #181.
cmlenz
parents:
649
diff
changeset
|
311 .. warning:: Unfortunately, code blocks are severely limited when running |
e162edb680cf
Add warning about using code blocks on Python 2.3. Closes #181.
cmlenz
parents:
649
diff
changeset
|
312 under Python 2.3: For example, it is not possible to access |
e162edb680cf
Add warning about using code blocks on Python 2.3. Closes #181.
cmlenz
parents:
649
diff
changeset
|
313 variables defined in outer scopes. If you plan to use code blocks |
e162edb680cf
Add warning about using code blocks on Python 2.3. Closes #181.
cmlenz
parents:
649
diff
changeset
|
314 extensively, it is strongly recommended that you run Python 2.4 |
e162edb680cf
Add warning about using code blocks on Python 2.3. Closes #181.
cmlenz
parents:
649
diff
changeset
|
315 or later. |
e162edb680cf
Add warning about using code blocks on Python 2.3. Closes #181.
cmlenz
parents:
649
diff
changeset
|
316 |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
317 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
318 .. _`error handling`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
319 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
320 Error Handling |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
321 ============== |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
322 |
606
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
323 By default, Genshi raises an ``UndefinedError`` if a template expression |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
324 attempts to access a variable that is not defined: |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
325 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
326 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
327 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
328 >>> from genshi.template import MarkupTemplate |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 >>> tmpl = MarkupTemplate('<p>${doh}</p>') |
606
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
330 >>> tmpl.generate().render('xhtml') |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
331 Traceback (most recent call last): |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
332 ... |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
333 UndefinedError: "doh" not defined |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
334 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
335 You can change this behavior by setting the variable lookup mode to "lenient". |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
336 In that case, accessing undefined variables returns an `Undefined` object, |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
337 meaning that the expression does not fail immediately. See below for details. |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
338 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
339 If you need to check whether a variable exists in the template context, use the |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
340 defined_ or the value_of_ function described below. To check for existence of |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
341 attributes on an object, or keys in a dictionary, use the ``hasattr()``, |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
342 ``getattr()`` or ``get()`` functions, or the ``in`` operator, just as you would |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
343 in regular Python code: |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
344 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
345 >>> from genshi.template import MarkupTemplate |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
346 >>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>') |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
347 >>> print tmpl.generate().render('xhtml') |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
348 <p>False</p> |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
349 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
350 .. note:: Lenient error handling was the default in Genshi prior to version 0.5. |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
351 Strict mode was introduced in version 0.4, and became the default in |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
352 0.5. The reason for this change was that the lenient error handling |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
353 was masking actual errors in templates, thereby also making it harder |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
354 to debug some problems. |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
355 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
356 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
357 .. _`lenient`: |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
358 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
359 Lenient Mode |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
360 ------------ |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
361 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
362 If you instruct Genshi to use the lenient variable lookup mode, it allows you |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
363 to access variables that are not defined, without raising an ``UndefinedError``. |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
364 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
365 This mode can be chosen by passing the ``lookup='lenient'`` keyword argument to |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
366 the template initializer, or by passing the ``variable_lookup='lenient'`` |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
367 keyword argument to the ``TemplateLoader`` initializer: |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
368 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
369 .. code-block:: pycon |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
370 |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
371 >>> from genshi.template import MarkupTemplate |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
372 >>> tmpl = MarkupTemplate('<p>${doh}</p>', lookup='lenient') |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 >>> print tmpl.generate().render('xhtml') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 <p></p> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 You *will* however get an exception if you try to call an undefined variable, or |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
377 do anything else with it, such as accessing its attributes: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
378 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
379 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 >>> from genshi.template import MarkupTemplate |
606
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
382 >>> tmpl = MarkupTemplate('<p>${doh.oops}</p>', lookup='lenient') |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 >>> print tmpl.generate().render('xhtml') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 Traceback (most recent call last): |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ... |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 UndefinedError: "doh" not defined |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 If you need to know whether a variable is defined, you can check its type |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
389 against the ``Undefined`` class, for example in a conditional directive: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
390 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
476
diff
changeset
|
391 .. code-block:: pycon |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 >>> from genshi.template import MarkupTemplate |
606
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
394 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</p>', |
37ff75bb4301
Changed the default error handling mode to "strict".
cmlenz
parents:
605
diff
changeset
|
395 ... lookup='lenient') |
442
97544725bb7f
Back out [510] and instead implement configurable error handling 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 >>> print tmpl.generate().render('xhtml') |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 <p>False</p> |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 Alternatively, the built-in functions defined_ or value_of_ can be used in this |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 case. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 Custom Modes |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ------------ |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 In addition to the built-in "lenient" and "strict" modes, it is also possible to |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 use a custom error handling mode. For example, you could use lenient error |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 handling in a production environment, while also logging a warning when an |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 undefined variable is referenced. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 See the API documentation of the ``genshi.template.eval`` module for details. |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 Built-in Functions & Types |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 ========================== |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 The following functions and types are available by default in template code, in |
97544725bb7f
Back out [510] and instead implement configurable error handling 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 addition to the standard built-ins that are available to all Python code. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
418 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
419 .. _`defined`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
420 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
421 ``defined(name)`` |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
422 ----------------- |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
423 This function determines whether a variable of the specified name exists in |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
424 the context data, and returns ``True`` if it does. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
425 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
426 .. _`value_of`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
427 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
428 ``value_of(name, default=None)`` |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
429 -------------------------------- |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
430 This function returns the value of the variable with the specified name if |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
431 such a variable is defined, and returns the value of the ``default`` |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
432 parameter if no such variable is defined. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
433 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
434 .. _`Markup`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
435 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
436 ``Markup(text)`` |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
437 ---------------- |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
438 The ``Markup`` type marks a given string as being safe for inclusion in markup, |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
439 meaning it will *not* be escaped in the serialization stage. Use this with care, |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
440 as not escaping a user-provided string may allow malicious users to open your |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
441 web site to cross-site scripting attacks. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
442 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
443 .. _`Undefined`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
444 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
445 ``Undefined`` |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
446 ---------------- |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
447 The ``Undefined`` type can be used to check whether a reference variable is |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
448 defined, as explained in `error handling`_. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
449 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
450 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
451 .. _`directives`: |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
452 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
453 ------------------- |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
454 Template Directives |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
455 ------------------- |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
456 |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
457 Directives provide control flow functionality for templates, such as conditions |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
458 or iteration. As the syntax for directives depends on whether you're using |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
459 markup or text templates, refer to the |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
460 `XML Template Language <xml-templates.html>`_ or |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
diff
changeset
|
461 `Text Template Language <text-templates.html>`_ pages for information. |