genshi/mirror: doc/templates.txt annotate

annotate doc/templates.txt @ 988:480cf1be291a trunk

Always include the test packages (otherwise sdists built on Python 2 don't work on Python 3 which is unexpected and confusing).

author	hodgestar
date	Sat, 26 Jan 2013 10:57:32 +0000
parents	e97cdbf09a18
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
875 5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	32 used to generate any kind of HTML or XML output, as they provide a number of
5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	33 advantages over simple text-based templates (such as automatic escaping of
5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	34 variable data).
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	35
875 5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	36 The following is a simple Genshi markup template:
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	37
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	38 .. 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	39
97544725bb7f Back out [510] and instead implement configurable error handling 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 <?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	41 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	42 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	43 ?>
97544725bb7f Back out [510] and instead implement configurable error handling 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 <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	45 <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	46 <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	47 </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	48
97544725bb7f Back out [510] and instead implement configurable error handling 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 <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	50 <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	51 <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	52 <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	53 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	54 </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	55 </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	56 </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	57 </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	58
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	60
875 5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	61 (a) a Python code block in a processing instruction
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	62 (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	63 (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	64 (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	65
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	66 The template would generate output similar to this:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	67
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	68 .. code-block:: genshi
445 ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	69
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	70 <html>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	71 <head>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	72 <title>A Genshi Template</title>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	73 </head>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	74
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	75 <body>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	76 <p>These are some of my favorite fruits:</p>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	77 <ul>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	78 <li>I like apples</li>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	79 <li>I like oranges</li>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	80 <li>I like kiwis</li>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	81 </ul>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	82 </body>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	83 </html>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	84
875 5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	85 A text template is a simple plain text document that can also contain
5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	86 embedded Python code. Text templates are intended to be used for simple
5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	87 non-markup text formats, such as the body of an plain text email. For
5c7454462cd3 Minor doc tweak. cmlenz parents: 853 diff changeset	88 example:
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	89
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	90 .. 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	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 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	93
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	95 #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	96 * $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	97 #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	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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	102 ----------
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	105 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	106
97544725bb7f Back out [510] and instead implement configurable error handling 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 * 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	108 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	109 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	110 * 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	111 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	112 * 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	113
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	114 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	115
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	116 .. 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	117
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	119 >>> 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	120 >>> stream = tmpl.generate(name='world')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	121 >>> 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	122 <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	123
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	124 .. 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	125 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	126
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	127 Using a text template is similar:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	128
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	129 .. 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	130
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	132 >>> 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	133 >>> stream = tmpl.generate(name='world')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	134 >>> 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	135 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	136
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	137 .. 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	138 ``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	139 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	140
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _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	142 .. _`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	143 .. _`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	144
884 e97cdbf09a18 Improve the template loader docs. cmlenz parents: 875 diff changeset	145 Using a `template loader`_ provides the advantage that “compiled” templates are
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	146 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	147 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	148 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	149 template loader would generally look as follows:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	150
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	151 .. 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	152
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	154 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	155 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	156 stream = tmpl.generate(title='Hello, world!')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	157 print(stream.render())
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	158
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	160 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	161
884 e97cdbf09a18 Improve the template loader docs. cmlenz parents: 875 diff changeset	162 .. _`template loader`: loader.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	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 .. _`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	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 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	168 ------------------------------------
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	171 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	172 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	173 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	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
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _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	177
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	178 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	179 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	180 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	181 ends:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	182
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	183 .. 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	184
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	186 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	187 >>> print(tmpl.generate(items=['first', 'second']))
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	188 <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	189
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	190 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	191 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	192 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	193 dictionary):
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	194
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	195 .. 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	196
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	198 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	199 >>> print(tmpl.generate(dict={'foo': 'bar'}))
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	200 <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	201
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	202 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	203 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	204 rather an exception of the type ``UndefinedError``. The same kind of error is
476 1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	205 raised when you try to use a top-level variable that is not in the context data.
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	206 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	207
97544725bb7f Back out [510] and instead implement configurable error handling 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
811 c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	209 Escaping
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	210 ========
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	211
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	212 If you need to include a literal dollar sign in the output where Genshi would
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	213 normally detect an expression, you can simply add another dollar sign:
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	214
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	215 .. code-block:: pycon
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	216
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	217 >>> from genshi.template import MarkupTemplate
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	218 >>> tmpl = MarkupTemplate('<em>$foo</em>') # Wanted "$foo" as literal output
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	219 >>> print(tmpl.generate())
811 c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	220 Traceback (most recent call last):
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	221 ...
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	222 UndefinedError: "foo" not defined
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	223 >>> tmpl = MarkupTemplate('<em>$$foo</em>')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	224 >>> print(tmpl.generate())
811 c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	225 <em>$foo</em>
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	226
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	227 But note that this is not necessary if the characters following the dollar sign
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	228 do not qualify as an expression. For example, the following needs no escaping:
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	229
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	230 .. code-block:: pycon
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	231
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	232 >>> tmpl = MarkupTemplate('<script>$(function() {})</script>')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	233 >>> print(tmpl.generate())
811 c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	234 <script>$(function() {})</script>
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	235
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	236 On the other hand, Genshi will always replace two dollar signs in text with a
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	237 single dollar sign, so you'll need to use three dollar signs to get two in the
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	238 output:
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	239
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	240 .. code-block:: pycon
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	241
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	242 >>> tmpl = MarkupTemplate('<script>$$$("div")</script>')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	243 >>> print(tmpl.generate())
811 c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	244 <script>$$("div")</script>
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	245
c42693ee739d Add doc section on expression escaping. Closes #282. cmlenz parents: 756 diff changeset	246
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	247 .. _`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	248
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 ===========
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	251
609 6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	252 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	253 processing instruction in XML templates:
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	254
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	255 .. 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	256
97544725bb7f Back out [510] and instead implement configurable error handling 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 <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	258 <?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	259 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	260 def greeting(name):
649 717bbfe5bbdc Fix typo in docs. Closes #153. cmlenz parents: 609 diff changeset	261 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	262 ${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	263 </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	264
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	265 This will produce the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	266
609 6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	267 .. 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	268
97544725bb7f Back out [510] and instead implement configurable error handling 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 <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	270 <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	271 </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	272
609 6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	273 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	274 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	275
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	276 .. code-block:: genshitext
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	277
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	278 {% python
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	279 from genshi.builder import tag
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	280 def greeting(name):
649 717bbfe5bbdc Fix typo in docs. Closes #153. cmlenz parents: 609 diff changeset	281 return 'Hello, %s!' % name
609 6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	282 %}
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	283 ${greeting('world')}
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	284
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	285 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	286
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	287 Hello, world!
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	288
6d4877844e28 Add support for Python code blocks in text templates using the new syntax. cmlenz parents: 606 diff changeset	289
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 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	291 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	292 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	293
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	294 .. 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	295 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	296
476 1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	297 Unlike expressions, Python code in ``<?python ?>`` processing instructions can
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	298 not use item and attribute access in an interchangeable manner. That means that
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	299 “dotted notation” is always attribute access, and vice-versa.
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	300
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	301 The support for Python code blocks in templates is not supposed to encourage
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	302 mixing application code into templates, which is generally considered bad
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	303 design. If you're using many code blocks, that may be a sign that you should
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	304 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	305
545 619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123. cmlenz parents: 510 diff changeset	306 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	307 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	308 ``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	309 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	310 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	311 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	312 using plain expressions.
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123. cmlenz parents: 510 diff changeset	313
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	314
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	315 .. _`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	316
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	318 ==============
97544725bb7f Back out [510] and instead implement configurable error handling 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
606 37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	320 By default, Genshi raises an ``UndefinedError`` if a template expression
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	321 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	322
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	323 .. 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	324
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	325 >>> 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	326 >>> tmpl = MarkupTemplate('<p>${doh}</p>')
606 37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	327 >>> tmpl.generate().render('xhtml')
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	328 Traceback (most recent call last):
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	329 ...
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	330 UndefinedError: "doh" not defined
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	331
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	332 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	333 In that case, accessing undefined variables returns an `Undefined` object,
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	334 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	335
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	336 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	337 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	338 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	339 ``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	340 in regular Python code:
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	341
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	342 >>> from genshi.template import MarkupTemplate
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	343 >>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	344 >>> print(tmpl.generate().render('xhtml'))
606 37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	345 <p>False</p>
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	346
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	347 .. 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	348 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	349 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	350 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	351 to debug some problems.
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	352
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	353
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	354 .. _`lenient`:
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 Lenient Mode
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	357 ------------
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 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	360 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	361
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	362 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	363 the template initializer, or by passing the ``variable_lookup='lenient'``
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	364 keyword argument to the ``TemplateLoader`` initializer:
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	365
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	366 .. code-block:: pycon
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	367
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	368 >>> from genshi.template import MarkupTemplate
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	369 >>> tmpl = MarkupTemplate('<p>${doh}</p>', lookup='lenient')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	370 >>> print(tmpl.generate().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	371 <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	372
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	374 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	375
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	376 .. 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	377
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> from genshi.template import MarkupTemplate
606 37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	379 >>> tmpl = MarkupTemplate('<p>${doh.oops}</p>', lookup='lenient')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	380 >>> print(tmpl.generate().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	381 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	382 ...
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	384
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	386 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	387
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	388 .. 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	389
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> from genshi.template import MarkupTemplate
606 37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	391 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</p>',
37ff75bb4301 Changed the default error handling mode to "strict". cmlenz parents: 605 diff changeset	392 ... lookup='lenient')
853 f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 811 diff changeset	393 >>> print(tmpl.generate().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	394 <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	395
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	397 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	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 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	400 ------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	403 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	404 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	405 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	406
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	408
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	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 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	414 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	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 .. _`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	417
97544725bb7f Back out [510] and instead implement configurable error handling 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 ``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	419 -----------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	421 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	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 .. _`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	424
97544725bb7f Back out [510] and instead implement configurable error handling 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 ``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	426 --------------------------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	428 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	429 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	430
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	432
97544725bb7f Back out [510] and instead implement configurable error handling 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 ``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	434 ----------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	436 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	437 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	438 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	439
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	441
97544725bb7f Back out [510] and instead implement configurable error handling 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 ``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	443 ----------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	445 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	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
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	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 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	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 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	455 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	456 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	457 `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	458 `Text Template Language <text-templates.html>`_ pages for information.

Mercurial > genshi > mirror

annotate doc/templates.txt @ 988:480cf1be291a trunk