cmlenz@226: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@226: 
cmlenz@226: ============================
cmlenz@230: Genshi XML Template Language
cmlenz@226: ============================
cmlenz@226: 
cmlenz@241: Genshi provides a XML-based template language that is heavily inspired by Kid_,
cmlenz@241: which in turn was inspired by a number of existing template languages, namely
cmlenz@241: XSLT_, TAL_, and PHP_.
cmlenz@226: 
cmlenz@226: .. _kid: http://kid-templating.org/
cmlenz@226: .. _python: http://www.python.org/
cmlenz@226: .. _xslt: http://www.w3.org/TR/xslt
cmlenz@226: .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
cmlenz@226: .. _php: http://www.php.net/
cmlenz@226: 
cmlenz@226: This document describes the template language and will be most useful as
cmlenz@241: reference to those developing Genshi XML templates. Templates are XML files of
cmlenz@241: some kind (such as XHTML) that include processing directives_ (elements or
cmlenz@226: attributes identified by a separate namespace) that affect how the template is
cmlenz@226: rendered, and template expressions_ that are dynamically substituted by
cmlenz@226: variable data.
cmlenz@226: 
cmlenz@226: 
cmlenz@226: .. contents:: Contents
cmlenz@226:    :depth: 3
cmlenz@226: .. sectnum::
cmlenz@226: 
cmlenz@226: ----------
cmlenz@226: Python API
cmlenz@226: ----------
cmlenz@226: 
cmlenz@230: The Python code required for templating with Genshi is generally based on the
cmlenz@226: following pattern:
cmlenz@226: 
cmlenz@241: * Attain a ``MarkupTemplate`` object from a string or file object containing
cmlenz@241:   the template XML source. This can either be done directly, or through a
cmlenz@226:   ``TemplateLoader`` instance.
cmlenz@226: * Call the ``generate()`` method of the template, passing any data that should
cmlenz@226:   be made available to the template as keyword arguments.
cmlenz@226: * Serialize the resulting stream using its ``render()`` method.
cmlenz@226: 
cmlenz@226: For example::
cmlenz@226: 
cmlenz@241:   from genshi.template import MarkupTemplate
cmlenz@226: 
cmlenz@241:   tmpl = MarkupTemplate('<h1>$title</h1>')
cmlenz@226:   stream = tmpl.generate(title='Hello, world!')
cmlenz@226:   print stream.render('xhtml')
cmlenz@226: 
cmlenz@226: That code would produce the following output::
cmlenz@226: 
cmlenz@226:   <h1>Hello, world!</h1>
cmlenz@226: 
cmlenz@226: However, if you want includes_ to work, you should attain the template instance
cmlenz@226: through a ``TemplateLoader``, and load the template from a file::
cmlenz@226: 
cmlenz@230:   from genshi.template import TemplateLoader
cmlenz@226: 
cmlenz@226:   loader = TemplateLoader([templates_dir])
cmlenz@226:   tmpl = loader.load('test.html')
cmlenz@226:   stream = tmpl.generate(title='Hello, world!')
cmlenz@226:   print stream.render('xhtml')
cmlenz@226: 
cmlenz@226: 
cmlenz@226: .. _`expressions`:
cmlenz@226: 
cmlenz@429: ------------------------------------
cmlenz@429: Template Expressions and Code Blocks
cmlenz@429: ------------------------------------
cmlenz@226: 
cmlenz@226: Python_ expressions can be used in text and attribute values. An expression is
cmlenz@226: substituted with the result of its evaluation against the template data.
cmlenz@226: Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in
cmlenz@226: curly braces (``{…}``).
cmlenz@226: 
cmlenz@394: If the expression starts with a letter and contains only letters, digits, dots,
cmlenz@394: and underscores, the curly braces may be omitted. In all other cases, the
cmlenz@394: braces are required so that the template processor knows where the expression
cmlenz@394: ends::
cmlenz@226: 
cmlenz@241:   >>> from genshi.template import MarkupTemplate
cmlenz@241:   >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
cmlenz@241:   >>> print tmpl.generate(items=['first', 'second'])
cmlenz@226:   <em>First item</em>
cmlenz@226: 
cmlenz@226: Expressions support the full power of Python. In addition, it is possible to
cmlenz@226: access items in a dictionary using “dotted notation” (i.e. as if they were
cmlenz@226: attributes), and vice-versa (i.e. access attributes as if they were items in a
cmlenz@226: dictionary)::
cmlenz@226: 
cmlenz@241:   >>> from genshi.template import MarkupTemplate
cmlenz@241:   >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
cmlenz@241:   >>> print tmpl.generate(dict={'foo': 'bar'})
cmlenz@226:   <em>bar</em>
cmlenz@226: 
cmlenz@429: Because there are two ways to access either attributes or items, expressions
cmlenz@429: do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
cmlenz@429: rather an exception of the type ``UndefinedError``. The same kind of error is
cmlenz@429: raised when you try to access a top-level variable that is not in the context
cmlenz@429: data.
cmlenz@244: 
cmlenz@244: 
cmlenz@429: .. _`code blocks`:
cmlenz@429: 
cmlenz@429: Code Blocks
cmlenz@429: ===========
cmlenz@429: 
cmlenz@429: XML templates also support full Python code blocks using the ``<?python ?>``
cmlenz@429: processing instruction::
cmlenz@429: 
cmlenz@429:   <div>
cmlenz@429:     <?python
cmlenz@429:         from genshi.builder import tag
cmlenz@429:         def greeting(name):
cmlenz@429:             return tag.b('Hello, %s!' % name') ?>
cmlenz@429:     ${greeting('world')}
cmlenz@429:   </div>
cmlenz@429: 
cmlenz@429: This will produce the following output::
cmlenz@429: 
cmlenz@429:   <div>
cmlenz@429:     <b>Hello, world!</b>
cmlenz@429:   </div>
cmlenz@429: 
cmlenz@429: Code blocks can import modules, define classes and functions, and basically do
cmlenz@429: anything you can do in normal Python code. What code blocks can *not* do is to
cmlenz@429: produce content that is included directly in the generated page.
cmlenz@429: 
cmlenz@429: .. note:: Using the ``print`` statement will print to the standard output
cmlenz@429:           stream, just as it does for other Python code in your application.
cmlenz@429: 
cmlenz@429: This feature is not supposed to encourage mixing application code into
cmlenz@429: templates, which is generally considered bad design. If you're using many code
cmlenz@429: blocks, that me be a sign that you should move such code into separate Python
cmlenz@429: modules.
cmlenz@429: 
cmlenz@429: 
cmlenz@429: Built-in Functions & Types
cmlenz@429: ==========================
cmlenz@429: 
cmlenz@429: The following functions and types are available by default in template code, in
cmlenz@429: addition to the standard built-ins that are available to all Python code.
cmlenz@429: 
cmlenz@429: ``defined(name)``
cmlenz@429: -----------------
cmlenz@429:  
cmlenz@429: This function determines whether a variable of the specified name exists in
cmlenz@429: the context data, and returns ``True`` if it does.
cmlenz@429:  
cmlenz@429: ``value_of(name, default=None)``
cmlenz@429: --------------------------------
cmlenz@429: 
cmlenz@429: This function returns the value of the variable with the specified name if
cmlenz@429: such a variable is defined, and returns the value of the ``default``
cmlenz@429: parameter if no such variable is defined.
cmlenz@429: 
cmlenz@429: ``Markup(text)``
cmlenz@429: ----------------
cmlenz@429: 
cmlenz@429: The ``Markup`` type marks a given string as being safe for inclusion in markup,
cmlenz@429: meaning it will *not* be escaped in the serialization stage. Use this with care,
cmlenz@429: as not escaping a user-provided string may allow malicious users to open your
cmlenz@429: web site to cross-site scripting attacks.
cmlenz@244: 
cmlenz@226: 
cmlenz@226: .. _`directives`:
cmlenz@226: 
cmlenz@226: -------------------
cmlenz@226: Template Directives
cmlenz@226: -------------------
cmlenz@226: 
cmlenz@226: Directives are elements and/or attributes in the template that are identified
cmlenz@230: by the namespace ``http://genshi.edgewall.org/``. They can affect how the
cmlenz@230: template is rendered in a number of ways: Genshi provides directives for
cmlenz@226: conditionals and looping, among others.
cmlenz@226: 
cmlenz@394: To use directives in a template, the namespace must be declared, which is
cmlenz@226: usually done on the root element::
cmlenz@226: 
cmlenz@226:   <html xmlns="http://www.w3.org/1999/xhtml"
cmlenz@230:         xmlns:py="http://genshi.edgewall.org/"
cmlenz@226:         lang="en">
cmlenz@226:     ...
cmlenz@226:   </html>
cmlenz@226: 
cmlenz@226: In this example, the default namespace is set to the XHTML namespace, and the
cmlenz@230: namespace for Genshi directives is bound to the prefix “py”.
cmlenz@226: 
cmlenz@226: All directives can be applied as attributes, and some can also be used as
cmlenz@226: elements. The ``if`` directives for conditionals, for example, can be used in
cmlenz@226: both ways::
cmlenz@226: 
cmlenz@226:   <html xmlns="http://www.w3.org/1999/xhtml"
cmlenz@230:         xmlns:py="http://genshi.edgewall.org/"
cmlenz@226:         lang="en">
cmlenz@226:     ...
cmlenz@226:     <div py:if="foo">
cmlenz@226:       <p>Bar</p>
cmlenz@226:     </div>
cmlenz@226:     ...
cmlenz@226:   </html>
cmlenz@226: 
cmlenz@226: This is basically equivalent to the following::
cmlenz@226: 
cmlenz@226:   <html xmlns="http://www.w3.org/1999/xhtml"
cmlenz@230:         xmlns:py="http://genshi.edgewall.org/"
cmlenz@226:         lang="en">
cmlenz@226:     ...
cmlenz@226:     <py:if test="foo">
cmlenz@226:       <div>
cmlenz@226:         <p>Bar</p>
cmlenz@226:       </div>
cmlenz@226:     </py:if>
cmlenz@226:     ...
cmlenz@226:   </html>
cmlenz@226: 
cmlenz@226: The rationale behind the second form is that directives do not always map
cmlenz@226: naturally to elements in the template. In such cases, the ``py:strip``
cmlenz@226: directive can be used to strip off the unwanted element, or the directive can
cmlenz@226: simply be used as an element.
cmlenz@226: 
cmlenz@226: 
cmlenz@237: Conditional Sections
cmlenz@226: ====================
cmlenz@226: 
cmlenz@235: .. _`py:if`:
cmlenz@226: 
cmlenz@235: ``py:if``
cmlenz@237: ---------
cmlenz@226: 
cmlenz@235: The element is only rendered if the expression evaluates to a truth value::
cmlenz@226: 
cmlenz@235:   <div>
cmlenz@235:     <b py:if="foo">${bar}</b>
cmlenz@235:   </div>
cmlenz@226: 
cmlenz@235: Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
cmlenz@235: would produce::
cmlenz@235: 
cmlenz@235:   <div>
cmlenz@235:     <b>Hello</b>
cmlenz@235:   </div>
cmlenz@235: 
cmlenz@235: This directive can also be used as an element::
cmlenz@235: 
cmlenz@235:   <div>
cmlenz@235:     <py:if test="foo">
cmlenz@235:       <b>${bar}</b>
cmlenz@235:     </py:if>
cmlenz@235:   </div>
cmlenz@226: 
cmlenz@226: .. _`py:choose`:
cmlenz@226: .. _`py:when`:
cmlenz@226: .. _`py:otherwise`:
cmlenz@226: 
cmlenz@237: ``py:choose``
cmlenz@237: -------------
cmlenz@226: 
cmlenz@237: The ``py:choose`` directive, in combination with the directives ``py:when``
cmlenz@404: and ``py:otherwise`` provides advanced conditional processing for rendering one
cmlenz@226: of several alternatives. The first matching ``py:when`` branch is rendered, or,
cmlenz@404: if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered.
cmlenz@226: 
cmlenz@226: If the ``py:choose`` directive is empty the nested ``py:when`` directives will
cmlenz@226: be tested for truth::
cmlenz@226: 
cmlenz@226:   <div py:choose="">
cmlenz@226:     <span py:when="0 == 1">0</span>
cmlenz@226:     <span py:when="1 == 1">1</span>
cmlenz@226:     <span py:otherwise="">2</span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: This would produce the following output::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <span>1</span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: If the ``py:choose`` directive contains an expression the nested ``py:when``
cmlenz@226: directives will be tested for equality to the parent ``py:choose`` value::
cmlenz@226: 
cmlenz@226:   <div py:choose="1">
cmlenz@226:     <span py:when="0">0</span>
cmlenz@226:     <span py:when="1">1</span>
cmlenz@226:     <span py:otherwise="">2</span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: This would produce the following output::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <span>1</span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: 
cmlenz@235: Looping
cmlenz@237: =======
cmlenz@226: 
cmlenz@235: .. _`py:for`:
cmlenz@226: 
cmlenz@235: ``py:for``
cmlenz@237: ----------
cmlenz@235: 
cmlenz@235: The element is repeated for every item in an iterable::
cmlenz@226: 
cmlenz@226:   <ul>
cmlenz@235:     <li py:for="item in items">${item}</li>
cmlenz@226:   </ul>
cmlenz@226: 
cmlenz@235: Given ``items=[1, 2, 3]`` in the context data, this would produce::
cmlenz@226: 
cmlenz@226:   <ul>
cmlenz@235:     <li>1</li><li>2</li><li>3</li>
cmlenz@226:   </ul>
cmlenz@226: 
cmlenz@235: This directive can also be used as an element::
cmlenz@226: 
cmlenz@235:   <ul>
cmlenz@235:     <py:for each="item in items">
cmlenz@235:       <li>${item}</li>
cmlenz@235:     </py:for>
cmlenz@235:   </ul>
cmlenz@235: 
cmlenz@235: 
cmlenz@235: Snippet Reuse
cmlenz@237: =============
cmlenz@226: 
cmlenz@226: .. _`py:def`:
cmlenz@226: .. _`macros`:
cmlenz@226: 
cmlenz@226: ``py:def``
cmlenz@237: ----------
cmlenz@226: 
cmlenz@226: The ``py:def`` directive can be used to create macros, i.e. snippets of
cmlenz@226: template code that have a name and optionally some parameters, and that can be
cmlenz@226: inserted in other places::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <p py:def="greeting(name)" class="greeting">
cmlenz@226:       Hello, ${name}!
cmlenz@226:     </p>
cmlenz@226:     ${greeting('world')}
cmlenz@226:     ${greeting('everyone else')}
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: The above would be rendered to::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <p class="greeting">
cmlenz@226:       Hello, world!
cmlenz@226:     </p>
cmlenz@226:     <p class="greeting">
cmlenz@226:       Hello, everyone else!
cmlenz@226:     </p>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@394: If a macro doesn't require parameters, it can be defined without the 
cmlenz@394: parenthesis. For example::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <p py:def="greeting" class="greeting">
cmlenz@226:       Hello, world!
cmlenz@226:     </p>
cmlenz@394:     ${greeting()}
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: The above would be rendered to::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <p class="greeting">
cmlenz@226:       Hello, world!
cmlenz@226:     </p>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: This directive can also be used as an element::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <py:def function="greeting(name)">
cmlenz@226:       <p class="greeting">Hello, ${name}!</p>
cmlenz@226:     </py:def>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: 
cmlenz@235: .. _Match Templates:
cmlenz@226: .. _`py:match`:
cmlenz@226: 
cmlenz@226: ``py:match``
cmlenz@237: ------------
cmlenz@226: 
cmlenz@226: This directive defines a *match template*: given an XPath expression, it
cmlenz@226: replaces any element in the template that matches the expression with its own
cmlenz@226: content.
cmlenz@226: 
cmlenz@226: For example, the match template defined in the following template matches any
cmlenz@226: element with the tag name “greeting”::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <span py:match="greeting">
cmlenz@226:       Hello ${select('@name')}
cmlenz@226:     </span>
cmlenz@226:     <greeting name="Dude" />
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: This would result in the following output::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <span>
cmlenz@226:       Hello Dude
cmlenz@226:     </span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: Inside the body of a ``py:match`` directive, the ``select(path)`` function is
cmlenz@226: made available so that parts or all of the original element can be incorporated
cmlenz@230: in the output of the match template. See [wiki:GenshiStream#UsingXPath] for
cmlenz@226: more information about this function.
cmlenz@226: 
cmlenz@226: This directive can also be used as an element::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <py:match path="greeting">
cmlenz@226:       <span>Hello ${select('@name')}</span>
cmlenz@226:     </py:match>
cmlenz@226:     <greeting name="Dude" />
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: 
cmlenz@235: Variable Binding
cmlenz@237: ================
cmlenz@226: 
cmlenz@226: .. _`with`:
cmlenz@226: 
cmlenz@226: ``py:with``
cmlenz@237: -----------
cmlenz@226: 
cmlenz@226: The ``py:with`` directive lets you assign expressions to variables, which can
cmlenz@226: be used to make expressions inside the directive less verbose and more
cmlenz@226: efficient. For example, if you need use the expression ``author.posts`` more
cmlenz@226: than once, and that actually results in a database query, assigning the results
cmlenz@226: to a variable using this directive would probably help.
cmlenz@226: 
cmlenz@226: For example::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <span py:with="y=7; z=x+10">$x $y $z</span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: Given ``x=42`` in the context data, this would produce::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <span>42 7 52</span>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: This directive can also be used as an element::
cmlenz@226: 
cmlenz@226:   <div>
cmlenz@226:     <py:with vars="y=7; z=x+10">$x $y $z</py:with>
cmlenz@226:   </div>
cmlenz@226: 
cmlenz@226: Note that if a variable of the same name already existed outside of the scope
cmlenz@226: of the ``py:with`` directive, it will **not** be overwritten. Instead, it
cmlenz@226: will have the same value it had prior to the ``py:with`` assignment.
cmlenz@230: Effectively, this means that variables are immutable in Genshi.
cmlenz@226: 
cmlenz@226: 
cmlenz@235: Structure Manipulation
cmlenz@237: ======================
cmlenz@235: 
cmlenz@235: .. _`py:attrs`:
cmlenz@235: 
cmlenz@235: ``py:attrs``
cmlenz@237: ------------
cmlenz@235: 
cmlenz@235: This directive adds, modifies or removes attributes from the element::
cmlenz@235: 
cmlenz@235:   <ul>
cmlenz@235:     <li py:attrs="foo">Bar</li>
cmlenz@235:   </ul>
cmlenz@235: 
cmlenz@235: Given ``foo={'class': 'collapse'}`` in the template context, this would
cmlenz@235: produce::
cmlenz@235: 
cmlenz@235:   <ul>
cmlenz@235:     <li class="collapse">Bar</li>
cmlenz@235:   </ul>
cmlenz@235: 
cmlenz@235: Attributes with the value ``None`` are omitted, so given ``foo={'class': None}``
cmlenz@235: in the context for the same template this would produce::
cmlenz@235: 
cmlenz@235:   <ul>
cmlenz@235:     <li>Bar</li>
cmlenz@235:   </ul>
cmlenz@235: 
cmlenz@235: This directive can only be used as an attribute.
cmlenz@235: 
cmlenz@235: 
cmlenz@235: .. _`py:content`:
cmlenz@235: 
cmlenz@235: ``py:content``
cmlenz@237: --------------
cmlenz@235: 
cmlenz@235: This directive replaces any nested content with the result of evaluating the
cmlenz@235: expression::
cmlenz@235: 
cmlenz@235:   <ul>
cmlenz@235:     <li py:content="bar">Hello</li>
cmlenz@235:   </ul>
cmlenz@235: 
cmlenz@235: Given ``bar='Bye'`` in the context data, this would produce::
cmlenz@235: 
cmlenz@235:   <ul>
cmlenz@235:     <li>Bye</li>
cmlenz@235:   </ul>
cmlenz@235: 
cmlenz@235: This directive can only be used as an attribute.
cmlenz@235: 
cmlenz@235: 
cmlenz@235: .. _`py:replace`:
cmlenz@235: 
cmlenz@235: ``py:replace``
cmlenz@237: --------------
cmlenz@235: 
cmlenz@235: This directive replaces the element itself with the result of evaluating the
cmlenz@235: expression::
cmlenz@235: 
cmlenz@235:   <div>
cmlenz@235:     <span py:replace="bar">Hello</span>
cmlenz@235:   </div>
cmlenz@235: 
cmlenz@235: Given ``bar='Bye'`` in the context data, this would produce::
cmlenz@235: 
cmlenz@235:   <div>
cmlenz@235:     Bye
cmlenz@235:   </div>
cmlenz@235: 
cmlenz@235: This directive can only be used as an attribute.
cmlenz@235: 
cmlenz@235: 
cmlenz@235: .. _`py:strip`:
cmlenz@235: 
cmlenz@235: ``py:strip``
cmlenz@237: ------------
cmlenz@235: 
cmlenz@235: This directive conditionally strips the top-level element from the output. When
cmlenz@235: the value of the ``py:strip`` attribute evaluates to ``True``, the element is
cmlenz@235: stripped from the output::
cmlenz@235: 
cmlenz@235:   <div>
cmlenz@235:     <div py:strip="True"><b>foo</b></div>
cmlenz@235:   </div>
cmlenz@235: 
cmlenz@235: This would be rendered as::
cmlenz@235: 
cmlenz@235:   <div>
cmlenz@235:     <b>foo</b>
cmlenz@235:   </div>
cmlenz@235: 
cmlenz@235: As a shorthand, if the value of the ``py:strip`` attribute is empty, that has
cmlenz@235: the same effect as using a truth value (i.e. the element is stripped).
cmlenz@235: 
cmlenz@235: 
cmlenz@226: .. _order:
cmlenz@226: 
cmlenz@226: Processing Order
cmlenz@226: ================
cmlenz@226: 
cmlenz@226: It is possible to attach multiple directives to a single element, although not
cmlenz@226: all combinations make sense. When multiple directives are encountered, they are
cmlenz@226: processed in the following order:
cmlenz@226: 
cmlenz@226: #. `py:def`_
cmlenz@226: #. `py:match`_
cmlenz@226: #. `py:when`_
cmlenz@226: #. `py:otherwise`_
cmlenz@226: #. `py:for`_
cmlenz@226: #. `py:if`_
cmlenz@226: #. `py:choose`_
cmlenz@226: #. `py:with`_
cmlenz@226: #. `py:replace`_
cmlenz@226: #. `py:content`_
cmlenz@226: #. `py:attrs`_
cmlenz@226: #. `py:strip`_
cmlenz@226: 
cmlenz@226: 
cmlenz@226: .. _includes:
cmlenz@226: 
cmlenz@226: --------
cmlenz@226: Includes
cmlenz@226: --------
cmlenz@226: 
cmlenz@226: To reuse common snippets of template code, you can include other files using
cmlenz@226: XInclude_.
cmlenz@226: 
cmlenz@226: .. _xinclude: http://www.w3.org/TR/xinclude/
cmlenz@226: 
cmlenz@226: For this, you need to declare the XInclude namespace (commonly bound to the
cmlenz@226: prefix “xi”) and use the ``<xi:include>`` element where you want the external
cmlenz@226: file to be pulled in::
cmlenz@226: 
cmlenz@226:   <html xmlns="http://www.w3.org/1999/xhtml"
cmlenz@230:         xmlns:py="http://genshi.edgewall.org/"
cmlenz@226:         xmlns:xi="http://www.w3.org/2001/XInclude">
cmlenz@226:     <xi:include href="base.html" />
cmlenz@226:     ...
cmlenz@226:   </html>
cmlenz@226: 
cmlenz@226: Include paths are relative to the filename of the template currently being
cmlenz@226: processed. So if the example above was in the file "``myapp/index.html``"
cmlenz@226: (relative to the template search path), the XInclude processor would look for
cmlenz@226: the included file at "``myapp/base.html``". You can also use Unix-style
cmlenz@226: relative paths, for example "``../base.html``" to look in the parent directory.
cmlenz@226: 
cmlenz@226: Any content included this way is inserted into the generated output instead of
cmlenz@226: the ``<xi:include>`` element. The included template sees the same context data.
cmlenz@226: `Match templates`_ and `macros`_ in the included template are also available to
cmlenz@226: the including template after the point it was included.
cmlenz@226: 
cmlenz@226: By default, an error will be raised if an included file is not found. If that's
cmlenz@226: not what you want, you can specify fallback content that should be used if the
cmlenz@226: include fails. For example, to to make the include above fail silently, you'd
cmlenz@273: write::
cmlenz@226: 
cmlenz@226:   <xi:include href="base.html"><xi:fallback /></xi:include>
cmlenz@226: 
cmlenz@273: See the `XInclude specification`_ for more about fallback content. Note though 
cmlenz@273: that Genshi currently only supports a small subset of XInclude.
cmlenz@273: 
cmlenz@273: .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
cmlenz@226: 
cmlenz@230: Incudes in Genshi are fully dynamic: Just like normal attributes, the `href`
cmlenz@226: attribute accepts expressions_, and directives_ can be used on the
cmlenz@226: ``<xi:include />`` element just as on any other element, meaning you can do
cmlenz@226: things like conditional includes::
cmlenz@226: 
cmlenz@226:   <xi:include href="${name}.html" py:if="not in_popup"
cmlenz@226:               py:for="name in ('foo', 'bar', 'baz')" />
cmlenz@226: 
cmlenz@226: 
cmlenz@226: .. _comments:
cmlenz@226: 
cmlenz@226: --------
cmlenz@226: Comments
cmlenz@226: --------
cmlenz@226: 
cmlenz@226: Normal XML/HTML comment syntax can be used in templates::
cmlenz@226: 
cmlenz@226:   <!-- this is a comment -->
cmlenz@226: 
cmlenz@226: However, such comments get passed through the processing pipeline and are by
cmlenz@226: default included in the final output. If that's not desired, prefix the comment
cmlenz@226: text with an exclamation mark::
cmlenz@226: 
cmlenz@226:   <!-- !this is a comment too, but one that will be stripped from the output -->
cmlenz@226: 
cmlenz@226: Note that it does not matter whether there's whitespace before or after the
cmlenz@226: exclamation mark, so the above could also be written as follows::
cmlenz@226: 
cmlenz@226:   <!--! this is a comment too, but one that will be stripped from the output -->