.. -*- mode: rst; encoding: utf-8 -*-

=============================
Genshi Text Template Language
=============================

In addition to the XML-based template language, Genshi provides a simple
text-based template language, intended for basic plain text generation needs.
The language is similar to Cheetah_ or Velocity_.

.. _cheetah: http://cheetahtemplate.org/
.. _velocity: http://jakarta.apache.org/velocity/

This document describes the template language and will be most useful as
reference to those developing Genshi text templates. Templates are text files of
some kind that include processing directives_ that affect how the template is
rendered, and template expressions that are dynamically substituted by
variable data.

See `Genshi Templating Basics <templates.html>`_ for general information on
embedding Python code in templates.


.. contents:: Contents
   :depth: 3
.. sectnum::


.. _`directives`:

-------------------
Template Directives
-------------------

Directives are lines starting with a ``#`` character followed immediately by
the directive name. They can affect how the template is rendered in a number of
ways: Genshi provides directives for conditionals and looping, among others.

Directives must be on separate lines, and the ``#`` character must be be the
first non-whitespace character on that line. Each directive must be “closed”
using a ``#end`` marker. You can add after the ``#end`` marker, for example to
document which directive is being closed, or even the expression associated with 
that directive. Any text after ``#end`` (but on the same line) is  ignored, 
and effectively treated as a comment.

If you want to include a literal ``#`` in the output, you need to escape it
by prepending a backslash character (``\``). Note that this is **not** required 
if the ``#`` isn't immediately followed by a letter, or it isn't the first
non-whitespace character on the line.


Conditional Sections
====================

.. _`#if`:

``#if``
---------

The content is only rendered if the expression evaluates to a truth value::

  #if foo
    ${bar}
  #end

Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
would produce::

    Hello


.. _`#choose`:
.. _`#when`:
.. _`#otherwise`:

``#choose``
-------------

The ``#choose`` directive, in combination with the directives ``#when`` and
``#otherwise`` provides advanced contional processing for rendering one of
several alternatives. The first matching ``#when`` branch is rendered, or, if
no ``#when`` branch matches, the ``#otherwise`` branch is be rendered.

If the ``#choose`` directive has no argument the nested ``#when`` directives
will be tested for truth::

  The answer is:
  #choose
    #when 0 == 1
      0
    #end
    #when 1 == 1
      1
    #end
    #otherwise
      2
    #end
  #end

This would produce the following output::

  The answer is:
      1

If the ``#choose`` does have an argument, the nested ``#when`` directives will
be tested for equality to the parent ``#choose`` value::

  The answer is:
  #choose 1
    #when 0
      0
    #end
    #when 1
      1
    #end
    #otherwise
      2
    #end
  #end

This would produce the following output::

  The answer is:
      1


Looping
=======

.. _`#for`:

``#for``
----------

The content is repeated for every item in an iterable::

  Your items:
  #for item in items
    * ${item}
  #end

Given ``items=[1, 2, 3]`` in the context data, this would produce::

  Your items
    * 1
    * 2
    * 3


Snippet Reuse
=============

.. _`#def`:
.. _`macros`:

``#def``
----------

The ``#def`` directive can be used to create macros, i.e. snippets of template
text that have a name and optionally some parameters, and that can be inserted
in other places::

  #def greeting(name)
    Hello, ${name}!
  #end
  ${greeting('world')}
  ${greeting('everyone else')}

The above would be rendered to::

    Hello, world!
    Hello, everyone else!

If a macro doesn't require parameters, it can be defined as well as called
without the parenthesis. For example::

  #def greeting
    Hello, world!
  #end
  ${greeting}

The above would be rendered to::

    Hello, world!


Variable Binding
================

.. _`#with`:

``#with``
-----------

The ``#with`` directive lets you assign expressions to variables, which can
be used to make expressions inside the directive less verbose and more
efficient. For example, if you need use the expression ``author.posts`` more
than once, and that actually results in a database query, assigning the results
to a variable using this directive would probably help.

For example::

  Magic numbers!
  #with y=7; z=x+10
    $x $y $z
  #end

Given ``x=42`` in the context data, this would produce::

  Magic numbers!
    42 7 52

Note that if a variable of the same name already existed outside of the scope
of the ``#with`` directive, it will **not** be overwritten. Instead, it will
have the same value it had prior to the ``#with`` assignment. Effectively,
this means that variables are immutable in Genshi.


.. _comments:

--------
Comments
--------

Lines where the first non-whitespace characters are ``##`` are removed from
the output, and can thus be used for comments. This can be escaped using a
backslash.