docs/src/frameworks.txt

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

Jinja registers itself in the baker template plugin system. If your framework
supports baker (currently `TurboGears`_ and `pylons`_) you can add it very
easily.

Pylons
------

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

.. sourcecode:: python

    from jinja import Environment, FileSystemLoader

    config.add_template_engine('jinja', {
        'jinja.environment': Environment(loader=FileSystemLoader('path/to/templates'))
    })

To make Jinja the default template engine change the `init_app` call to
something like this:

.. sourcecode:: python

    config.init_app(global_conf, app_conf, package='yourproject',
                    template_engine='jinja')

If you load templates using dotted notation the ``'.html'`` to the filename.
You can override this using ``jinja.exception``. eg:

.. sourcecode:: python

    config.add_template_engine('jinja', {
        'jinja.environment': ...,
        'jinja.extension': 'tmpl'
    })

Note that you have to use a trailing slash to load templates if you want to
specify the extension. Otherwise use the dotted notation:

.. sourcecode:: python

    render_template('/index.html')
    render_template('index')
    
    render_template('/modules/userlist.html')
    render_template('modules.userlist')


TurboGears
----------

Integrating Jinja into TurboGears works pretty much the same.

Basically all you have to do is to edit the application configuration file at
``application/config/app.cfg`` and change `global.tg.defaultview` and
provide the jinja options:

.. sourcecode:: ini

    [global]
    tg.defaultview = 'jinja'
    jinja.init_callback = yourapplication.yourmodule.setup_function

Now you have to edit the file `yourapplication.yourmodule` and add a
`setup_function` callback that creates an environment:

.. sourcecode:: python

    from jinja import Environment, FileSystemLoader

    def setup_function(options):
        return Environment(loader=FileSystemLoader('path/to/templates'))

This solution isn't the best but currently the only thing you can do. There is
a discussion about improving the plugin interface so that this can be solved
in a more elegant way.

Also here exists the same limitation regarding dotted notation, see the
snipped and information in the pylons section.


.. _TurboGears: http://www.turbogears.org/
.. _pylons: http://www.pylonshq.com/