Text templates
==============

Piglet includes a text-based templating language, combining the best
of Jinja2, Twig and Kajiki.

Syntax
------

Statements are enclosed in ``{% ... %}``, and interpolations in ``${..}``:


.. code:: text

    {% for line in address %}
    ${line}
    {% end %}

Available directives are the same as for the HTML templating language, see
:doc:`directives` for details.

Whitespace control
------------------

If a ``{% … %}`` tag is on a line by itself,
then that line is removed from the output.

If a ``{% … %}`` tag is at the end of a line with other content,
the first newline after the tag is removed.

For example, this:

.. code:: text

    Twas brillig
    {% if toves %}
      And the slithy toves
    {% end %}
    Did gyre and gimble
     In the wabe

Becomes this:

.. code:: text

    Twas brillig
      And the slithy toves
    Did gyre and gimble
      In the wabe

The symbols ``+`` or ``-`` can be placed at the start or end of a tag to
cause the corresponding whitespace to be stripped or preserved, so:

.. code:: text

    One
    {%- if two -%}
      Two
    {%- end -%}
    Three

Becomes:

.. code:: text


    OneTwoThree

Similarly,

.. code:: text

    Four
    {%- if five %} Five {% end -%}
    Six

Becomes

.. code:: text

    Four Five Six


Directives
----------

Most directives are the same as the HTML template directives, and are
terminated with an ``{% end %}`` statement.


Extends, block
``````````````

``{% extends %}`` and ``{% block %}`` are used to implement template inheritance.
See :ref:`py-extends` for details:

.. code:: text

    {% extends "path/to/template.txt" %}
    {% block intro %}
    Custom intro text
    {% end %}
    {% end %}


``ignore-missing`` can be used to supress
:class:`~piglet.exceptions.TemplateNotFound`
exceptions:

.. code:: text

    {% extends "$master_template" ignore-missing %}
    {% block intro %}
    Custom intro text
    {% end %}
    {% end %}



Include
``````````````
.. code:: text

    {% include "info.txt" %}


``ignore-missing`` can be used to supress
:class:`~piglet.exceptions.TemplateNotFound`
exceptions:

.. code:: text

    {% include "$content_path" ignore-missing %}


Import
``````
.. code:: text

    {% import "path/to/template.txt" as common %}

    ${common.header()}



for
```
.. code:: text

    {% for i in range(5) %}
        $i
    {% end %}



if...else
`````````
.. code:: text

    {% if foo is None %}
        this
    {% else %}
        that
    {% end %}


def
```
.. code:: text

    {% def format_amount(x) %}
        {% if amount >= 0 %}
            ${amount}€
        {% else %}
            (${amount}€)
        {% end %}
    {% end %}


with
````
.. code:: text

    {% with x = 5 %}
        {% for i in range(x) %}
            $x
        {% end %}
    {% end %}


trans, transname
````````````````

Used to mark up translated text and dynamic value placeholders.

.. code:: text

    {% trans %}
        hello {% transname name %}$user.get_full_name(){% end %}
    {% end %}