Jinja

Framework Integration

Navigation

Contents

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:

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:

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.