docs/src/frameworks.txt

=====================
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.

.. _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