genshi/mirror: doc/templates.txt annotate

annotate doc/templates.txt @ 583:61e072802b62 stable-0.4.x

Ported [696] to 0.4.x branch.

author	cmlenz
date	Wed, 01 Aug 2007 16:23:41 +0000
parents	26cf27d4f2b3
children	619340e2d805

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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	35 The following illustrates a very basic Genshi markup template:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	36
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	65 The template would generate output similar to this:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	66
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	86 formats, such as the body of an plain text email. For example:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	87
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	112 For example:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	113
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	122 Using a text template is similar:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	123
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	142 template loader would generally look as follows:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	143
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	173 ends:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	174
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	185 dictionary):
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	186
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
478 3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	197 raised when you try to use a top-level variable that is not in the context data.
3068d554de19 Ported [576] to 0.4.x. 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 ?>``
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	207 processing instruction:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	208
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	219 This will produce the following output:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	220
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 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
478 3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	234 Unlike expressions, Python code in ``<?python ?>`` processing instructions can
3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	235 not use item and attribute access in an interchangeable manner. That means that
3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	236 “dotted notation” is always attribute access, and vice-versa.
3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	237
3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	238 The support for Python code blocks in templates is not supposed to encourage
3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	239 mixing application code into templates, which is generally considered bad
3068d554de19 Ported [576] to 0.4.x. cmlenz parents: 445 diff changeset	240 design. If you're using many code blocks, that may be a sign that you should
3068d554de19 Ported [576] to 0.4.x. 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
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	243 .. 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	244
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	245
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	246 .. _`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	247
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	248 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	249 ==============
97544725bb7f Back out [510] and instead implement configurable error handling 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 By default, Genshi allows you to access variables that are not defined, without
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	252 raising a ``NameError`` exception as regular Python code would:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	253
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	254 .. 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	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 >>> 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	257 >>> 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	258 >>> 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	259 <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	260
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	261 You will however get an exception if you try to call an undefined variable, or
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	262 do anything else with it, such as accessing its attributes:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	263
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	264 .. 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	265
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	266 >>> 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	267 >>> 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	268 >>> 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	269 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	270 ...
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	272
97544725bb7f Back out [510] and instead implement configurable error handling 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 If you need to know whether a variable is defined, you can check its type
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	274 against the ``Undefined`` class, for example in a conditional directive:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	275
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	276 .. 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	277
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	279 >>> 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	280 >>> 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	281 <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	282
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	283 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	284 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	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 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	287 -----------
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	290 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	291 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	292
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	294 the template initializer, or by passing the ``variable_lookup='strict'`` keyword
511 26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	295 argument to the ``TemplateLoader`` initializer:
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	296
26cf27d4f2b3 Ported [611:614] to 0.4.x branch. cmlenz parents: 478 diff changeset	297 .. 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	298
97544725bb7f Back out [510] and instead implement configurable error handling 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 >>> 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	300 >>> 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	301 >>> 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	302 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	303 ...
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	304 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	305
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	307 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	308 ``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	309
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. 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	311 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	312 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	313 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	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 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	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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	319 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	320 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	321 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	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 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	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 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	327 ==========================
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: diff changeset	328
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	330 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	331
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	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 ``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	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 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	337 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	338
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	340
97544725bb7f Back out [510] and instead implement configurable error handling 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 ``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	342 --------------------------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	344 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	345 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	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 .. _`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	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 ``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	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 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	352 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	353 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	354 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	355
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	357
97544725bb7f Back out [510] and instead implement configurable error handling 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 ``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	359 ----------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	361 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	362
97544725bb7f Back out [510] and instead implement configurable error handling 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 .. _`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	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 -------------------
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	368 -------------------
97544725bb7f Back out [510] and instead implement configurable error handling 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
97544725bb7f Back out [510] and instead implement configurable error handling 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 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	371 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	372 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	373 `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	374 `Text Template Language <text-templates.html>`_ pages for information.

Mercurial > genshi > mirror

annotate doc/templates.txt @ 583:61e072802b62 stable-0.4.x