Framework Integration — Jinja Documentation

# Jinja

## 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:

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