genshi/mirror: doc/templates.txt annotate

annotate doc/templates.txt @ 545:619340e2d805 trunk

Support for Python code blocks in templates can now be disabled. Closes #123.

author	cmlenz
date	Thu, 28 Jun 2007 23:00:24 +0000
parents	1bdccd3bda00
children	1da8de3e5e51 acf7c5ee36e7

rev	line source
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	2
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	3 ========================
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	4 Genshi Templating Basics
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	5 ========================
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	6
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	7 Genshi provides a template engine that can be used for generating either
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	8 markup (such as HTML_ or XML_) or plain text. While both share some of the
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	9 syntax (and much of the underlying implementation) they are essentially
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	10 separate languages.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	11
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	12 .. _html: http://www.w3.org/html/
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	13 .. _xml: http://www.w3.org/XML/
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	14
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	15 This document describes the common parts of the template engine and will be most
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	16 useful as reference to those developing Genshi templates. Templates are XML or
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	17 plain text files that include processing directives_ that affect how the
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	18 template is rendered, and template expressions_ that are dynamically substituted
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	19 by variable data.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	20
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	21
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	22 .. contents:: Contents
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	23 :depth: 3
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	24 .. sectnum::
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	25
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	26 --------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	27 Synopsis
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	28 --------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	29
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	30 A Genshi markup template is a well-formed XML document with embedded Python
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	31 used for control flow and variable substitution. Markup templates should be
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	32 used to generate any kind of HTML or XML output, as they provide many advantages
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	33 over simple text-based templates (such as automatic escaping of strings).
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	34
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	35 The following illustrates a very basic Genshi markup template:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	36
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	37 .. code-block:: genshi
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	38
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	39 <?python
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	40 title = "A Genshi Template"
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	41 fruits = ["apple", "orange", "kiwi"]
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	42 ?>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	43 <html xmlns:py="http://genshi.edgewall.org/">
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	44 <head>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	45 <title py:content="title">This is replaced.</title>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	46 </head>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	47
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	48 <body>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	49 <p>These are some of my favorite fruits:</p>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	50 <ul>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	51 <li py:for="fruit in fruits">
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	52 I like ${fruit}s
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	53 </li>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	54 </ul>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	55 </body>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	56 </html>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	57
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	58 This example shows:
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	59
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	60 (a) a Python code block, using a processing instruction
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	61 (b) the Genshi namespace declaration
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	62 (c) usage of templates directives (``py:content`` and ``py:for``)
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	63 (d) an inline Python expression (``${fruit}``).
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	64
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	65 The template would generate output similar to this:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	66
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	67 .. code-block:: genshi
445 ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	68
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	69 <html>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	70 <head>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	71 <title>A Genshi Template</title>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	72 </head>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	73
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	74 <body>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	75 <p>These are some of my favorite fruits:</p>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	76 <ul>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	77 <li>I like apples</li>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	78 <li>I like oranges</li>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	79 <li>I like kiwis</li>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	80 </ul>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	81 </body>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	82 </html>
ec7890aa7c0b Add documentation page on the plugin API. cmlenz parents: 442 diff changeset	83
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	84 A text template is a simple plain text document that can also contain embedded
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	85 Python code. Text templates can be used to generate simple non-markup text
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	86 formats, such as the body of an plain text email. For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	87
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	88 .. code-block:: genshitext
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	89
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	90 Dear $name,
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	91
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	92 These are some of my favorite fruits:
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	93 #for fruit in fruits
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	94 * $fruit
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	95 #end
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	96
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	97
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	98 ----------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	99 Python API
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	100 ----------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	101
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	102 The Python code required for templating with Genshi is generally based on the
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	103 following pattern:
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	104
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	105 * Attain a ``MarkupTemplate`` or ``TextTemplate`` object from a string or
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	106 file-like object containing the template source. This can either be done
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	107 directly, or through a ``TemplateLoader`` instance.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	108 * Call the ``generate()`` method of the template, passing any data that should
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	109 be made available to the template as keyword arguments.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	110 * Serialize the resulting stream using its ``render()`` method.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	111
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	112 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	113
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	114 .. code-block:: pycon
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	115
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	116 >>> from genshi.template import MarkupTemplate
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	117 >>> tmpl = MarkupTemplate('<h1>Hello, $name!</h1>')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	118 >>> stream = tmpl.generate(name='world')
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> print stream.render()
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	120 <h1>Hello, world!</h1>
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	121
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	122 Using a text template is similar:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	123
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	124 .. 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	125
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	126 >>> 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	127 >>> 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	128 >>> stream = tmpl.generate(name='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	129 >>> print stream.render()
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	130 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	131
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. note:: See the Serialization_ section of the `Markup Streams`_ page 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	133 information on configuring template output options.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	134
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _serialization: streams.html#serialization
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	137
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	138 Using a template loader provides the advantage that “compiled” templates are
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	139 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	140 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	141 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	142 template loader would generally look as follows:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	143
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	144 .. 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	145
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	147 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	148 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	149 stream = tmpl.generate(title='Hello, world!')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	150 print stream.render()
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	151
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	153 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	154
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	157
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	160 ------------------------------------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	161
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	162 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	163 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	164 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	165 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	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
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _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	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 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	171 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	172 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	173 ends:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	174
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	175 .. 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	176
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	178 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	179 >>> print tmpl.generate(items=['first', 'second'])
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	180 <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	181
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	182 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	183 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	184 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	185 dictionary):
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	186
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	187 .. 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	188
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	190 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	191 >>> print tmpl.generate(dict={'foo': 'bar'})
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	192 <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	193
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	194 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	195 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	196 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	197 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	198 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	199
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	202
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	204 ===========
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	205
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	206 XML templates also support full Python code blocks using the ``<?python ?>``
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	207 processing instruction:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	208
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	209 .. 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	210
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	211 <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	212 <?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	213 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	214 def greeting(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	215 return tag.b('Hello, %s!' % 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	216 ${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	217 </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	218
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	219 This will produce the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	220
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	221 .. 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	222
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	223 <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	224 <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	225 </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	226
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	227 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	228 anything you can do in normal Python code. What code blocks can not do is 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	229 produce content that is included directly in the generated page.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	230
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	231 .. 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	232 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	233
476 1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	234 Unlike expressions, Python code in ``<?python ?>`` processing instructions can
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	235 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	236 “dotted notation” is always attribute access, and vice-versa.
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	237
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	238 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	239 mixing application code into templates, which is generally considered bad
1bb01fce61ba Update documentation to reflect changes in [573]. cmlenz parents: 445 diff changeset	240 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	241 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	242
545 619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123. cmlenz parents: 510 diff changeset	243 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	244 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	245 ``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	246 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	247 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	248 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	249 using plain expressions.
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123. cmlenz parents: 510 diff changeset	250
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	251 .. note:: Code blocks are not currently supported in text templates.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	252
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	253
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	254 .. _`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	255
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	257 ==============
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 By default, Genshi allows you to access variables that are not defined, without
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	260 raising a ``NameError`` exception as regular Python code would:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	261
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	262 .. 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	263
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	265 >>> tmpl = MarkupTemplate('<p>${doh}</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	266 >>> print tmpl.generate().render('xhtml')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	267 <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	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 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	270 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	271
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	272 .. 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	273
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	274 >>> 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	275 >>> tmpl = MarkupTemplate('<p>${doh.oops}</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	276 >>> print tmpl.generate().render('xhtml')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	277 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	278 ...
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	279 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	280
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	281 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	282 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	283
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	284 .. 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	285
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	286 >>> 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	287 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</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	288 >>> print tmpl.generate().render('xhtml')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	289 <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	290
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	291 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	292 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	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 Strict Mode
97544725bb7f Back out [510] and instead implement configurable error handling 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 -----------
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	297 In addition to the default "lenient" error handling, Genshi lets you use a less
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	298 forgiving mode if you prefer errors blowing up loudly instead of being ignored
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	299 silently.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	300
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	301 This mode can be chosen by passing the ``lookup='strict'`` keyword argument 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	302 the template initializer, or by passing the ``variable_lookup='strict'`` keyword
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	303 argument to the ``TemplateLoader`` initializer:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	304
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 476 diff changeset	305 .. 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	306
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	307 >>> 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	308 >>> tmpl = MarkupTemplate('<p>${doh}</p>', lookup='strict')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	309 >>> print tmpl.generate().render('xhtml')
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	310 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	311 ...
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	312 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	313
97544725bb7f Back out [510] and instead implement configurable error handling 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 When using strict mode, any reference to an undefined variable, as well as
97544725bb7f Back out [510] and instead implement configurable error handling 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 trying to access an non-existing item or attribute of an object, will cause 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	316 ``UndefinedError`` to be raised immediately.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	317
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	318 .. note:: While this mode is currently not the default, it may be promoted 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	319 the default in future versions of Genshi. In general, 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	320 lenient error handling mode can be considered dangerous as it silently
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	321 ignores typos.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	322
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	323 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	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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	327 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	328 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	329 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	330
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	331 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	332
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	333
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	334 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	335 ==========================
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	336
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	337 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	338 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	339
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	340 .. _`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	341
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	342 ``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	343 -----------------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	344 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	345 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	346
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	347 .. _`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	348
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	349 ``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	350 --------------------------------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	351 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	352 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	353 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	354
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	355 .. _`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	356
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	357 ``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	358 ----------------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	359 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	360 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	361 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	362 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	363
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	364 .. _`Undefined`:
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	365
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	366 ``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	367 ----------------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	368 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	369 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	370
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	373
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	374 -------------------
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	375 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	376 -------------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	379 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	380 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	381 `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	382 `Text Template Language <text-templates.html>`_ pages for information.

Mercurial > genshi > mirror

annotate doc/templates.txt @ 545:619340e2d805 trunk