Skip to main content

Unobtrusive jinja2 integration in Django

Project description

© 2014 Thomas Khyn

Unobtrusive jinja2 integration in Django

Freely inspired from django-jinja and django-jinja2, as none of them met all my expectations!

Compatible with django 1.4 to 1.7 and relevant python versions (2.7 to 3.4).


  • Install djinga using the method of your choice

  • Add ‘djinga’ to your INSTALLED_APPS

  • Change the TEMPLATE_LOADERS settings to:

  • Add the relevant settings for jinja2

How it works

By default, a template will be rendered using Django’s built-in template engine if it has a .html, .htm, .djhtml or .djhtm file extension. If it has a .jjhtml or .jjhtm file extension, it will be rendered by Jinja2, using the setting values provided in django’s setting module.



A list or tuple of file extensions (with or without the leading dot) for templates that should be rendered with Django’s internal template engine.

Defaults to ('html', 'htm', 'jjhtml', 'jjhtm')


A list or tuple of the file extensions (with or without the leading dot) for templates that should be rendered with Jinja2.

Defaults to ('jjhtml', 'jjhtm')


A function taking as sole argument the path of the template file and returning True if the file should be rendered with Jinja2. Defaults to a function returning True if the extension is in JINJA2_JJ_EXTS


A tuple or list of extensions to be loaded by jinja2 (as python objects or paths to the python objects). Some extensions are shipped with djinga under djinga.ext.*.


The jinja2 environment’s constructor keyword arguments as a dictionary.


The jinja2 globals as a dictionary.


The jinja2 filters as a dictionary.


A tuple or list of module paths to load globals and filters from. This advantageously complements or replaces JINJA_GLOBALS and JINJA2_FILTERS. See Adding globals and filters for details.

Jinja2 extensions

Djinga comes with several Jinja2 extensions:


Provides a {% static 'path' %} tag to refer to Django’s staticfiles directory


Provides a {% css 'rel/path/to/file.css' %} tag that generates a HTML link element refering to the css file located at a relative path in a css directory. The css directory’s path can be defined relatively to Django’s staticfiles directory through the setting JINJA2_STATIC_CSS


Same as djinga.ext.css but generates a HTML script element refering to a javascript file. The js directory’s relative path can be set through the setting JINJA2_STATIC_JS

Simply concatenates django’s MEDIA_URL to the argument provided


From a PR on coffin. Provides a {% django %}{% enddjango %} tag to include django template language in a jinja2 template. For this tag to work, the django.core.context_processors.request context processor must be enabled.


From coffin Provides a Django-like {% csrf_token %} tag.


Provides a tag for URL reversing, similar to the django templates one.

djinga.ext.htmlcompress.HTMLCompress / SelectiveHTMLCompress

Based on Armin Ronacher’s version. Eliminates useless whitespace at template compilation time without extra overhead.

Django template tags

The following tags are available in any django template explicitly loading djinga_tags using the {% load djinga_tags %} statement.


Overrides the standard {% extends %} tag and enables it to refer to jinja2 files as well as normal django template files. While the template engine for the current file remains Django’s one, the template engine for the extended file can be either Jinja2 or Django, depending on the file extension (in JINJA2_DJ_EXTS or JINJA2_JJ_EXTS)

Adding globals and filters

A straightforward way to add globals and filters and make them available from your Jinja2 templates is to add them to the JINJA2_GLOBALS or the JINJA2_FILTERS in the settings module.

However, this is not always convenient nor possible (import loops), and djinga therefore provides a way to ease this process, through the jj_global and jj_filter decorators in combination with the JINJA2_LOAD_FROM setting.

Basically, the decorators mark the functions as Jinja2 globals or filters, while the setting (a list of module paths) indicates djinga where to look for them.

A short example is better than long explanations, so here we go.


from djinga.register import jj_filter, jj_global

def my_tag(*args, **kw):

def my_filter(*args, **kw)


is equivalent to this:

def my_tag(*args):

def my_filter(*args, **kw)

from my_module import my_tag, my_filter
JINJA2_GLOBALS = {'my_tag': my_tag}
JINJA2_FILTERS = {'my_filter': my_filter}

…with the significant advantage of not requiring a possibly issue-prone import statement in the settings module.

The jj_global and jj_filter decorators are compatible with any of the Jinja2 built-in decorators. They do not affect the behavior nor the signature of the decorated function, so you can use it normally (as a normal Django template tag or filter, for example).

The collected globals and filters are appended to the ones already specified in JINJA2_GLOBALS and JINJA2_FILTERS.

makemesssages management command

Adapted from coffin.

Djinga overrides the Django makemessages core management command to include the specific Jinja2 translation tags and ensure the strings marked for translation in Jinja2 templates appear in the translations dictionary.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution (24.9 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page