=====================
Framework Integration
=====================

Starting with Jinja 1.1 it's possible to embed Jinja into some of the existing
frameworks a lot easier. When speaking of frameworks we only refer to `Pylons`_
which has a working implementation of the TurboGears template specification.

Since the whole situation is problematic because of various reasons (kid
specific, uses dotted names for template loading, package name prefix etc.)
we worked around some of the problems by using pylons specific workarounds.

Jinja also ships an implementation for a hypothetical template abstraction layer
called `General Template Interface`_ which isn't implemented by any existing
framework so far. This specification however tries to solve the problems that
exist in Buffet.


Buffet
======

The buffet specification proposes that templates are named in dotted names. That
means `foo.bar` and not `foo/bar.html`. The dotted notation has the disadvantage
that you cannot specify the filename extension. In recent pylons versions it's
however possible to load templates with their native path too if you prefix the
template name with a foreslash (`/foo/bar.html`). If you don't specify the
extension it will assume `.html` for the dotted notation.

Here the list of configuration values:

======================= ======================================================
``jinja.extension``     The template extension when templates are loaded using
                        the dotted notation. Defaults to ``html``.
``jinja.environment``   If this is provided it must be the only configuration
                        value and it's used as jinja environment. In that
                        case all other configuration parameters except of
                        ``jinja.extension`` are ignored.
``jinja.searchpath``    If provided a new file system loader with this
                        search path is instanciated.
``jinja.package``       Name of the python package containing the
                        templates. If this and ``package_path`` is
                        defined a `PackageLoader` is used.
``jinja.package_path``  Path to the templates inside of a package.
``jinja.loader_func``   Function that takes the name of the template to
                        load. If it returns a string or unicode object
                        it's used to load a template. If the return
                        value is None it's considered missing.
``jinja.getmtime_func`` Function used to check if templates requires
                        reloading. Has to return the UNIX timestamp of
                        the last template change or 0 if this template
                        does not exist or requires updates at any cost.
``jinja.use_memcache``  Set this to ``True`` to enable memory caching.
                        This is usually a good idea in production mode,
                        but disable it during development since it won't
                        reload template changes automatically.
                        This only works in persistent environments like
                        FastCGI.
``jinja.memcache_size`` Number of template instance you want to cache.
                        Defaults to ``40``.
``jinja.cache_folder``  Set this to an existing directory to enable
                        caching of templates on the file system. Note
                        that this only affects templates transformed
                        into python code. Default is ``None`` which means
                        that caching is disabled.
``jinja.auto_reload``   Set this to `False` for a slightly better
                        performance. In that case of `getmtime_func`
                        not being provided this won't have an effect.
======================= ======================================================

All other options that start with `jinja.` are automatically forwarded to the
environment constructor.

In pylons for example you can use jinja as buffet plugin like this:

Edit the `yourproject/config/middleware.py` and add this to `config.init_app`:

.. sourcecode:: python

    config.add_template_engine('jinja', '', {
        'jinja.package':            'yourapplication',
        'jinja.package_path':       'res/templates',
        'jinja.use_memcache':       True
    })

Note that it's a good idea to set the second parameter to an empty string.
It's meant to be used as replacement for the turbogears package name but
Jinja assumes that the name of the template does not include the package
path.

You can then render the template in the view like this:

.. sourcecode:: python

    class ExampleController(BaseController):

        def index(self):
            c.title = "Your Page"
            c.message = 'hi'
            return render_response('jinja', 'test_template')

        def download(self):
            c.title = "Downloads"
            c.downloads = [1, 2, 3]
            return render_response('jinja', '/downloads.html')

With the settings from above rendering the `index` action will result in
rendering the template ``res/templates/test_template.html`` where res is
a folder in the ``yourapplication`` python package.

The `downloads` action uses the pylons specific leading foreslash notation.


General Template Interface
==========================

Because nobody implemented this specification so far it's not documented here
but in the sourcecode of the `plugin module`_. The specification itself is
explained on the pocoo trac on the `General Template Interface`_ wiki page.


Django
======

Using Jinja in django is straightforward because django has a pretty low
level response interface. Just have a look at the `developer recipies`_,
there are some examples for django.  Starting with Jinja 1.2 there is also
a contrib module that simplifies using Jinja in an unicode enabled django.

Quickstart
----------

To get started execute the following code at the bottom of your settings.py
or in some general application file such as urls.py or a central module. The
only thing that matters is that it's executed right *after* the settings
were set up and *before* `django.contrib.jinja` is imported::

    from jinja.contrib import djangosupport
    djangosupport.configure()

What this does is setting up a Jinja environment for this django instance
with loaders for `TEMPLATE_DIRS` etc.  It also converts a couple of default
django filters such as `date` and `timesince` which are not available in
Jinja per default.  If you want to change the list you can provide others
by passing a list with filter import names as `convert_filters` keyword
argument.

All other keyword arguments are forwarded to the environment.  If you want
to provide a loader yourself pass it a loader keyword argument.

Rendering Templates
-------------------

To render a template you can use the functions `render_to_string` or
`render_to_response` from the `django.contrib.jinja` module::

    from django.contrib.jinja import render_to_response
    resp = render_to_response('Hello {{ username }}!', {
        'username':     req.session['username']
    }, req)

`render_to_string` and `render_to_response` take at least the name of
the template as argument, then the optional dict which will become the
context.  If you also provide a request object as third argument the
context processors will be applied.

`render_to_response` also takes a forth parameter which can be the
content type which defaults to `DEFAULT_CONTENT_TYPE`.

Converting Filters
------------------

One of the useful objects provided by `django.contrib.jinja` is the
`register` object which can be used to register filters, tests and
global objects.  You can also convert any filter django provides in
a Jinja filter using `convert_django_filter`::

    from django.contrib.jinja import register, convert_django_filter
    from django.template.defaultfilters import floatformat

    register.filter(convert_django_filter(floatformat), 'floatformat')

Available methods on the `register` object:

``object (obj[, name])``
    Register a new global as name or with the object's name.
    Returns the function object unchanged so that you can use
    it as decorator if no name is provided.

``filter (func[, name])``
    Register a function as filter with the name provided or
    the object's name as filtername.
    Returns the function object unchanged so that you can use
    it as decorator if no name is provided.

``test (func[, name])``
    Register a function as test with the name provided or the
    object's name as testname.
    Returns the function object unchanged so that you can use
    it as decorator if no name is provided.

``context_inclusion (func, template[, name])``
    Register a function with a name provided or the func object's
    name in the global namespace that acts as subrender function.

    func is called with the callers context as dict and the
    arguments and keywords argument of the inclusion function.
    The function should then process the context and return a
    new context or the same context object. Afterwards the
    template is rendered with this context.

    Example::

        def add_author(context, author=None):
            if author is not None:
                author = Author.objects.get(name=author)
            context['author'] = author
            return context

        register.context_inclusion(add_author, 'author_details.html',
                                   'render_author_details')

    You can use it in the template like this then::

        {{ render_author_details('John Doe') }}

``clean_inclusion (func, template[, name[, run_processors]])``
    Works like `context_inclusion` but doesn't use the calles
    context but an empty context. If `run_processors` is `True`
    it will lookup the context for a `request` object and pass
    it to the render function to apply context processors.



.. _Pylons: http://www.pylonshq.com/
.. _General Template Interface: http://trac.pocoo.org/wiki/GeneralTemplateInterface
.. _plugin module: http://trac.pocoo.org/browser/jinja/trunk/jinja/plugin.py
.. _developer recipies: devrecipies.txt
