===========
Using Jinja
===========

Using Jinja in the application side is very basic. All you have to do
is to import the ``Template`` and ``Context`` class. Additionally you
need a loader which handles the template imports::

    from jinja import Template, Context, FileSystemLoader

    t = Template('templatename', FileSystemLoader('path/to/the/templates'))
    c = Context({
        'users': [
            {'name': 'someone', 'id': 1, 'visible': True},
            {'name': 'notme', 'id': 2, 'visible': True},
            {'name': 'peter', 'id': 3, 'visible': False}
        ]
    })
    print t.render(c)

The template ``templatename.html`` in ``path/to/the/templates`` might look
like this::

    <ul id="userlist">
    {% for user in users %}
      {% if user.visible %}
        {% define shown true %}
        <li><a href="/users/{{ user.id }}/">{{ user.name|escapexml }}</a></li>
      {% endif %}
    {% endfor %}
    {% if not shown %}
      <li><strong>no users found</strong></li>
    {% endif %}
    </ul>

Loaders
=======

There are three loaders shipped with Jinja:

FileSystemLoader
----------------

Create it with::

    loader = FileSystemLoader('searchpath/')

This loader will look for templates named ``NAME.html`` and doesn't cache anything.


CachedFileSystemLoader
----------------------

Create this loader using::

    loader = CachedFileSystemLoader('searchpath/'[, 'cachedir/'])

Works like the ``FileSystemLoader`` but caches the reparsed nodelist in the cachdir.
If cachedir is not given it will cache it in the searchpath but with a "." prefix.

.. admonition:: Note

    Please notice that cached templates are much faster then reparsing them each
    request because Jinja will save the preparsed nodelist in a dump.


StringLoader
------------

The ``StringLoader`` is a very basic loader without support for template inheritance,
but allows the loading of templates stored in a string::

    template = '''{{ "Hello World" }}'''
    print Template(template, StringLoader())


Unicode Support
===============

Jinja comes with built-in Unicode support. As a matter of fact, the return
value of ``Template.render()`` will be a Python unicode object.

Unfortunately, most text is still stored in some form of encoding, so normal
strings must be converted to Unicode.

The template
------------

Each template loader can be given a ``charset`` argument which defaults to
``"utf-8"``::

    loader = FileSystemLoader('path', charset='latin-1')

This tells the loader that all templates it processes are encoded in the 
``latin-1`` encoding.

The string loader of course doesn't use the ``charset`` if you "load" Unicode
strings.

The context
-----------

Every string that is stored in your context (whether directly or tucked away in
a list or dict) and used in the template will eventually have to be converted to
Unicode too. Therefore, the context, too, takes a ``charset`` argument (which
again defaults to ``"utf-8"``)::

    context = Context({'thing': 'Kse'}, charset='latin-1')
    template.render(context)

Unicode strings in the context are not concerned as they needn't be converted.

You can only specify one encoding per context, so if you have strings that use
another charset you have two options:

- convert them to unicode before putting them into the context
- put them into the context as normal strings and use the ``decode`` filter::

    {{ russianstring | decode "koi8-r" }}

When it encounters an encoding issue, Jinja will raise the
``TemplateCharsetError`` exception.
