genshi/genshi-test: doc/xml-templates.txt annotate

annotate doc/xml-templates.txt @ 431:747baa1cd597

* Don't allow `style` attributes by default in the `HTMLSanitizer`. Closes #97. * In case `style` attributes are explicitly allowed, also handle unicode escapes correctly.

author	cmlenz
date	Thu, 22 Mar 2007 18:13:02 +0000
parents	6911f3c5a7e8
children	ff7c72b52fb2

rev	line source
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	2
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	3 ============================
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	4 Genshi XML Template Language
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	5 ============================
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	6
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	7 Genshi provides a XML-based template language that is heavily inspired by Kid_,
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	8 which in turn was inspired by a number of existing template languages, namely
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	9 XSLT_, TAL_, and PHP_.
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	10
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	11 .. _kid: http://kid-templating.org/
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	12 .. _python: http://www.python.org/
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	13 .. _xslt: http://www.w3.org/TR/xslt
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	15 .. _php: http://www.php.net/
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	16
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	17 This document describes the template language and will be most useful as
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	18 reference to those developing Genshi XML templates. Templates are XML files of
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	19 some kind (such as XHTML) that include processing directives_ (elements or
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	20 attributes identified by a separate namespace) that affect how the template is
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	21 rendered, and template expressions_ that are dynamically substituted by
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	22 variable data.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	23
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	24
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	25 .. contents:: Contents
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	26 :depth: 3
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	27 .. sectnum::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	28
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	29 ----------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	30 Python API
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	31 ----------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	32
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	33 The Python code required for templating with Genshi is generally based on the
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	34 following pattern:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	35
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	36 * Attain a ``MarkupTemplate`` object from a string or file object containing
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	37 the template XML source. This can either be done directly, or through a
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	38 ``TemplateLoader`` instance.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	39 * Call the ``generate()`` method of the template, passing any data that should
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	40 be made available to the template as keyword arguments.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	41 * Serialize the resulting stream using its ``render()`` method.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	42
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	43 For example::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	44
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	45 from genshi.template import MarkupTemplate
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	46
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	47 tmpl = MarkupTemplate('<h1>$title</h1>')
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	48 stream = tmpl.generate(title='Hello, world!')
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	49 print stream.render('xhtml')
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	50
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	51 That code would produce the following output::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	52
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	53 <h1>Hello, world!</h1>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	54
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	55 However, if you want includes_ to work, you should attain the template instance
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	56 through a ``TemplateLoader``, and load the template from a file::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	57
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	58 from genshi.template import TemplateLoader
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	59
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	60 loader = TemplateLoader([templates_dir])
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	61 tmpl = loader.load('test.html')
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	62 stream = tmpl.generate(title='Hello, world!')
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	63 print stream.render('xhtml')
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	64
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	65
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	66 .. _`expressions`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	67
429 6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	68 ------------------------------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	69 Template Expressions and Code Blocks
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	70 ------------------------------------
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	71
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	72 Python_ expressions can be used in text and attribute values. An expression is
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	73 substituted with the result of its evaluation against the template data.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	74 Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	75 curly braces (``{…}``).
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	76
394 ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	77 If the expression starts with a letter and contains only letters, digits, dots,
ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	78 and underscores, the curly braces may be omitted. In all other cases, the
ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	79 braces are required so that the template processor knows where the expression
ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	80 ends::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	81
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	82 >>> from genshi.template import MarkupTemplate
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	83 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	84 >>> print tmpl.generate(items=['first', 'second'])
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	85 <em>First item</em>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	86
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	87 Expressions support the full power of Python. In addition, it is possible to
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	88 access items in a dictionary using “dotted notation” (i.e. as if they were
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	89 attributes), and vice-versa (i.e. access attributes as if they were items in a
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	90 dictionary)::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	91
241 bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	92 >>> from genshi.template import MarkupTemplate
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	93 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
bbed6d426678 * Added basic documentation for the text-based template language. cmlenz parents: 237 diff changeset	94 >>> print tmpl.generate(dict={'foo': 'bar'})
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	95 <em>bar</em>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	96
429 6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	97 Because there are two ways to access either attributes or items, expressions
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	98 do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	99 rather an exception of the type ``UndefinedError``. The same kind of error is
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	100 raised when you try to access a top-level variable that is not in the context
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	101 data.
244 78ae64ef822e Fixes for the text template docs. cmlenz parents: 241 diff changeset	102
78ae64ef822e Fixes for the text template docs. cmlenz parents: 241 diff changeset	103
429 6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	104 .. _`code blocks`:
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	105
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	106 Code Blocks
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	107 ===========
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	108
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	109 XML templates also support full Python code blocks using the ``<?python ?>``
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	110 processing instruction::
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	111
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	112 <div>
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	113 <?python
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	114 from genshi.builder import tag
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	115 def greeting(name):
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	116 return tag.b('Hello, %s!' % name') ?>
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	117 ${greeting('world')}
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	118 </div>
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	119
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	120 This will produce the following output::
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	121
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	122 <div>
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	123 <b>Hello, world!</b>
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	124 </div>
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	125
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	126 Code blocks can import modules, define classes and functions, and basically do
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	127 anything you can do in normal Python code. What code blocks can not do is to
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	128 produce content that is included directly in the generated page.
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	129
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	130 .. note:: Using the ``print`` statement will print to the standard output
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	131 stream, just as it does for other Python code in your application.
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	132
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	133 This feature is not supposed to encourage mixing application code into
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	134 templates, which is generally considered bad design. If you're using many code
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	135 blocks, that me be a sign that you should move such code into separate Python
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	136 modules.
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	137
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	138
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	139 Built-in Functions & Types
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	140 ==========================
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	141
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	142 The following functions and types are available by default in template code, in
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	143 addition to the standard built-ins that are available to all Python code.
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	144
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	145 ``defined(name)``
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	146 -----------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	147
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	148 This function determines whether a variable of the specified name exists in
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	149 the context data, and returns ``True`` if it does.
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	150
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	151 ``value_of(name, default=None)``
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	152 --------------------------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	153
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	154 This function returns the value of the variable with the specified name if
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	155 such a variable is defined, and returns the value of the ``default``
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	156 parameter if no such variable is defined.
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	157
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	158 ``Markup(text)``
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	159 ----------------
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	160
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	161 The ``Markup`` type marks a given string as being safe for inclusion in markup,
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	162 meaning it will not be escaped in the serialization stage. Use this with care,
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	163 as not escaping a user-provided string may allow malicious users to open your
6911f3c5a7e8 Updated docs for code blocks and changed error handling. cmlenz parents: 404 diff changeset	164 web site to cross-site scripting attacks.
244 78ae64ef822e Fixes for the text template docs. cmlenz parents: 241 diff changeset	165
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	166
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	167 .. _`directives`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	168
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	169 -------------------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	170 Template Directives
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	171 -------------------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	172
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	173 Directives are elements and/or attributes in the template that are identified
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	174 by the namespace ``http://genshi.edgewall.org/``. They can affect how the
24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	175 template is rendered in a number of ways: Genshi provides directives for
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	176 conditionals and looping, among others.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	177
394 ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	178 To use directives in a template, the namespace must be declared, which is
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	179 usually done on the root element::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	180
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	181 <html xmlns="http://www.w3.org/1999/xhtml"
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	182 xmlns:py="http://genshi.edgewall.org/"
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	183 lang="en">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	184 ...
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	185 </html>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	186
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	187 In this example, the default namespace is set to the XHTML namespace, and the
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	188 namespace for Genshi directives is bound to the prefix “py”.
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	189
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	190 All directives can be applied as attributes, and some can also be used as
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	191 elements. The ``if`` directives for conditionals, for example, can be used in
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	192 both ways::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	193
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	194 <html xmlns="http://www.w3.org/1999/xhtml"
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	195 xmlns:py="http://genshi.edgewall.org/"
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	196 lang="en">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	197 ...
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	198 <div py:if="foo">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	199 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	200 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	201 ...
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	202 </html>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	203
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	204 This is basically equivalent to the following::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	205
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	206 <html xmlns="http://www.w3.org/1999/xhtml"
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	207 xmlns:py="http://genshi.edgewall.org/"
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	208 lang="en">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	209 ...
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	210 <py:if test="foo">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	211 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	212 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	213 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	214 </py:if>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	215 ...
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	216 </html>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	217
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	218 The rationale behind the second form is that directives do not always map
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	219 naturally to elements in the template. In such cases, the ``py:strip``
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	220 directive can be used to strip off the unwanted element, or the directive can
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	221 simply be used as an element.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	222
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	223
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	224 Conditional Sections
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	225 ====================
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	226
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	227 .. _`py:if`:
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	228
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	229 ``py:if``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	230 ---------
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	231
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	232 The element is only rendered if the expression evaluates to a truth value::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	233
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	234 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	235 <b py:if="foo">${bar}</b>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	236 </div>
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	237
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	238 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	239 would produce::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	240
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	241 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	242 <b>Hello</b>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	243 </div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	244
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	245 This directive can also be used as an element::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	246
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	247 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	248 <py:if test="foo">
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	249 <b>${bar}</b>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	250 </py:if>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	251 </div>
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	252
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	253 .. _`py:choose`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	254 .. _`py:when`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	255 .. _`py:otherwise`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	256
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	257 ``py:choose``
ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	258 -------------
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	259
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	260 The ``py:choose`` directive, in combination with the directives ``py:when``
404 ec05506d1bda Fix a couple of typos in the docs. Closes #99. cmlenz parents: 394 diff changeset	261 and ``py:otherwise`` provides advanced conditional processing for rendering one
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	262 of several alternatives. The first matching ``py:when`` branch is rendered, or,
404 ec05506d1bda Fix a couple of typos in the docs. Closes #99. cmlenz parents: 394 diff changeset	263 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered.
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	264
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	265 If the ``py:choose`` directive is empty the nested ``py:when`` directives will
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	266 be tested for truth::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	267
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	268 <div py:choose="">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	269 <span py:when="0 == 1">0</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	270 <span py:when="1 == 1">1</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	271 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	272 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	273
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	274 This would produce the following output::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	275
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	276 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	277 <span>1</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	278 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	279
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	280 If the ``py:choose`` directive contains an expression the nested ``py:when``
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	281 directives will be tested for equality to the parent ``py:choose`` value::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	282
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	283 <div py:choose="1">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	284 <span py:when="0">0</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	285 <span py:when="1">1</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	286 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	287 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	288
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	289 This would produce the following output::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	290
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	291 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	292 <span>1</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	293 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	294
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	295
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	296 Looping
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	297 =======
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	298
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	299 .. _`py:for`:
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	300
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	301 ``py:for``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	302 ----------
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	303
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	304 The element is repeated for every item in an iterable::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	305
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	306 <ul>
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	307 <li py:for="item in items">${item}</li>
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	308 </ul>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	309
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	310 Given ``items=[1, 2, 3]`` in the context data, this would produce::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	311
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	312 <ul>
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	313 <li>1</li><li>2</li><li>3</li>
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	314 </ul>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	315
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	316 This directive can also be used as an element::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	317
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	318 <ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	319 <py:for each="item in items">
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	320 <li>${item}</li>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	321 </py:for>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	322 </ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	323
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	324
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	325 Snippet Reuse
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	326 =============
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	327
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	328 .. _`py:def`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	329 .. _`macros`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	330
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	331 ``py:def``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	332 ----------
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	333
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	334 The ``py:def`` directive can be used to create macros, i.e. snippets of
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	335 template code that have a name and optionally some parameters, and that can be
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	336 inserted in other places::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	337
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	338 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	339 <p py:def="greeting(name)" class="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	340 Hello, ${name}!
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	341 </p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	342 ${greeting('world')}
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	343 ${greeting('everyone else')}
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	344 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	345
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	346 The above would be rendered to::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	347
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	348 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	349 <p class="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	350 Hello, world!
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	351 </p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	352 <p class="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	353 Hello, everyone else!
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	354 </p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	355 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	356
394 ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	357 If a macro doesn't require parameters, it can be defined without the
ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	358 parenthesis. For example::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	359
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	360 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	361 <p py:def="greeting" class="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	362 Hello, world!
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	363 </p>
394 ebc7c1a3bc4d Minor doc fixes. cmlenz parents: 354 diff changeset	364 ${greeting()}
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	365 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	366
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	367 The above would be rendered to::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	368
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	369 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	370 <p class="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	371 Hello, world!
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	372 </p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	373 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	374
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	375 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	376
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	377 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	378 <py:def function="greeting(name)">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	379 <p class="greeting">Hello, ${name}!</p>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	380 </py:def>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	381 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	382
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	383
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	384 .. _Match Templates:
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	385 .. _`py:match`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	386
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	387 ``py:match``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	388 ------------
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	389
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	390 This directive defines a match template: given an XPath expression, it
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	391 replaces any element in the template that matches the expression with its own
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	392 content.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	393
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	394 For example, the match template defined in the following template matches any
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	395 element with the tag name “greeting”::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	396
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	397 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	398 <span py:match="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	399 Hello ${select('@name')}
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	400 </span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	401 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	402 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	403
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	404 This would result in the following output::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	405
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	406 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	407 <span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	408 Hello Dude
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	409 </span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	410 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	411
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	412 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	413 made available so that parts or all of the original element can be incorporated
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	414 in the output of the match template. See [wiki:GenshiStream#UsingXPath] for
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	415 more information about this function.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	416
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	417 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	418
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	419 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	420 <py:match path="greeting">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	421 <span>Hello ${select('@name')}</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	422 </py:match>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	423 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	424 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	425
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	426
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	427 Variable Binding
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	428 ================
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	429
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	430 .. _`with`:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	431
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	432 ``py:with``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	433 -----------
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	434
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	435 The ``py:with`` directive lets you assign expressions to variables, which can
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	436 be used to make expressions inside the directive less verbose and more
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	437 efficient. For example, if you need use the expression ``author.posts`` more
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	438 than once, and that actually results in a database query, assigning the results
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	439 to a variable using this directive would probably help.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	440
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	441 For example::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	442
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	443 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	444 <span py:with="y=7; z=x+10">$x $y $z</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	445 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	446
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	447 Given ``x=42`` in the context data, this would produce::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	448
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	449 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	450 <span>42 7 52</span>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	451 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	452
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	453 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	454
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	455 <div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	456 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	457 </div>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	458
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	459 Note that if a variable of the same name already existed outside of the scope
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	460 of the ``py:with`` directive, it will not be overwritten. Instead, it
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	461 will have the same value it had prior to the ``py:with`` assignment.
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	462 Effectively, this means that variables are immutable in Genshi.
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	463
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	464
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	465 Structure Manipulation
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	466 ======================
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	467
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	468 .. _`py:attrs`:
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	469
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	470 ``py:attrs``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	471 ------------
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	472
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	473 This directive adds, modifies or removes attributes from the element::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	474
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	475 <ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	476 <li py:attrs="foo">Bar</li>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	477 </ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	478
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	479 Given ``foo={'class': 'collapse'}`` in the template context, this would
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	480 produce::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	481
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	482 <ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	483 <li class="collapse">Bar</li>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	484 </ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	485
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	486 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}``
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	487 in the context for the same template this would produce::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	488
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	489 <ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	490 <li>Bar</li>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	491 </ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	492
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	493 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	494
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	495
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	496 .. _`py:content`:
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	497
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	498 ``py:content``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	499 --------------
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	500
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	501 This directive replaces any nested content with the result of evaluating the
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	502 expression::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	503
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	504 <ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	505 <li py:content="bar">Hello</li>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	506 </ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	507
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	508 Given ``bar='Bye'`` in the context data, this would produce::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	509
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	510 <ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	511 <li>Bye</li>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	512 </ul>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	513
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	514 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	515
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	516
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	517 .. _`py:replace`:
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	518
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	519 ``py:replace``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	520 --------------
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	521
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	522 This directive replaces the element itself with the result of evaluating the
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	523 expression::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	524
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	525 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	526 <span py:replace="bar">Hello</span>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	527 </div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	528
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	529 Given ``bar='Bye'`` in the context data, this would produce::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	530
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	531 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	532 Bye
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	533 </div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	534
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	535 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	536
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	537
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	538 .. _`py:strip`:
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	539
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	540 ``py:strip``
237 ad52b350e132 Flatten outline of XML templating documentation. cmlenz parents: 235 diff changeset	541 ------------
235 b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	542
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	543 This directive conditionally strips the top-level element from the output. When
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	544 the value of the ``py:strip`` attribute evaluates to ``True``, the element is
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	545 stripped from the output::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	546
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	547 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	548 <div py:strip="True"><b>foo</b></div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	549 </div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	550
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	551 This would be rendered as::
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	552
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	553 <div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	554 <b>foo</b>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	555 </div>
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	556
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	557 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	558 the same effect as using a truth value (i.e. the element is stripped).
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	559
b3cabd49de75 Beautified the HTML docs a bit. cmlenz parents: 230 diff changeset	560
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	561 .. _order:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	562
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	563 Processing Order
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	564 ================
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	565
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	566 It is possible to attach multiple directives to a single element, although not
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	567 all combinations make sense. When multiple directives are encountered, they are
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	568 processed in the following order:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	569
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	570 #. `py:def`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	571 #. `py:match`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	572 #. `py:when`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	573 #. `py:otherwise`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	574 #. `py:for`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	575 #. `py:if`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	576 #. `py:choose`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	577 #. `py:with`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	578 #. `py:replace`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	579 #. `py:content`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	580 #. `py:attrs`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	581 #. `py:strip`_
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	582
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	583
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	584 .. _includes:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	585
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	586 --------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	587 Includes
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	588 --------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	589
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	590 To reuse common snippets of template code, you can include other files using
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	591 XInclude_.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	592
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	593 .. _xinclude: http://www.w3.org/TR/xinclude/
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	594
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	595 For this, you need to declare the XInclude namespace (commonly bound to the
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	596 prefix “xi”) and use the ``<xi:include>`` element where you want the external
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	597 file to be pulled in::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	598
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	599 <html xmlns="http://www.w3.org/1999/xhtml"
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	600 xmlns:py="http://genshi.edgewall.org/"
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	601 xmlns:xi="http://www.w3.org/2001/XInclude">
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	602 <xi:include href="base.html" />
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	603 ...
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	604 </html>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	605
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	606 Include paths are relative to the filename of the template currently being
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	607 processed. So if the example above was in the file "``myapp/index.html``"
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	608 (relative to the template search path), the XInclude processor would look for
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	609 the included file at "``myapp/base.html``". You can also use Unix-style
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	610 relative paths, for example "``../base.html``" to look in the parent directory.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	611
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	612 Any content included this way is inserted into the generated output instead of
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	613 the ``<xi:include>`` element. The included template sees the same context data.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	614 `Match templates`_ and `macros`_ in the included template are also available to
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	615 the including template after the point it was included.
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	616
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	617 By default, an error will be raised if an included file is not found. If that's
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	618 not what you want, you can specify fallback content that should be used if the
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	619 include fails. For example, to to make the include above fail silently, you'd
273 4afa86e2ad83 Small doc fix. cmlenz parents: 244 diff changeset	620 write::
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	621
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	622 <xi:include href="base.html"><xi:fallback /></xi:include>
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	623
273 4afa86e2ad83 Small doc fix. cmlenz parents: 244 diff changeset	624 See the `XInclude specification`_ for more about fallback content. Note though
4afa86e2ad83 Small doc fix. cmlenz parents: 244 diff changeset	625 that Genshi currently only supports a small subset of XInclude.
4afa86e2ad83 Small doc fix. cmlenz parents: 244 diff changeset	626
4afa86e2ad83 Small doc fix. cmlenz parents: 244 diff changeset	627 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	628
230 24757b771651 Renamed Markup to Genshi in repository. cmlenz parents: 226 diff changeset	629 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href`
226 09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	630 attribute accepts expressions_, and directives_ can be used on the
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	631 ``<xi:include />`` element just as on any other element, meaning you can do
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	632 things like conditional includes::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	633
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	634 <xi:include href="${name}.html" py:if="not in_popup"
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	635 py:for="name in ('foo', 'bar', 'baz')" />
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	636
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	637
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	638 .. _comments:
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	639
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	640 --------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	641 Comments
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	642 --------
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	643
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	644 Normal XML/HTML comment syntax can be used in templates::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	645
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	646 <!-- this is a comment -->
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	647
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	648 However, such comments get passed through the processing pipeline and are by
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	649 default included in the final output. If that's not desired, prefix the comment
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	650 text with an exclamation mark::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	651
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	652 <!-- !this is a comment too, but one that will be stripped from the output -->
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	653
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	654 Note that it does not matter whether there's whitespace before or after the
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	655 exclamation mark, so the above could also be written as follows::
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	656
09f869a98149 Add reStructuredText documentation files. cmlenz parents: diff changeset	657 <!--! this is a comment too, but one that will be stripped from the output -->

Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 431:747baa1cd597