Jinja2 Support

Django Compressor comes with support for Jinja2 via an extension.

In-Request Compression

In order to use Django Compressor’s Jinja2 extension we would need to pass compressor.contrib.jinja2ext.CompressorExtension into environment:

import jinja2
from compressor.contrib.jinja2ext import CompressorExtension

env = jinja2.Environment(extensions=[CompressorExtension])

From now on, you can use same code you’d normally use within Django templates:

from django.conf import settings
template = env.from_string('\n'.join([
    '{% compress css %}',
    '<link rel="stylesheet" href="{{ STATIC_URL }}css/one.css" type="text/css" charset="utf-8">',
    '{% endcompress %}',
]))
template.render({'STATIC_URL': settings.STATIC_URL})

Offline Compression

Usage

First, you will need to configure COMPRESS_JINJA2_GET_ENVIRONMENT so that Compressor can retrieve the Jinja2 environment for rendering. This can be a lambda or function that returns a Jinja2 environment.

Then, run the following compress command along with an --engine parameter. The parameter can be either jinja2 or django (default). For example, ./manage.py compress --engine jinja2.

Using both Django and Jinja2 templates

There may be a chance that the Jinja2 parser is used to parse Django templates if you have a mixture of Django and Jinja2 templates in the same location(s). This should not be a problem since the Jinja2 parser will likely raise a template syntax error, causing Compressor to skip the erroneous template safely. (Vice versa for Django parser).

Templates of both engines can be compressed like this:

  • ./manage.py compress --engine django --engine jinja2

However, it is still recommended that you do not mix Django and Jinja2 templates in the same project.

Limitations

  • Does not support {% import %} and similar blocks within {% compress %} blocks.

  • Does not support {{super()}}.

  • All other filters, globals and language constructs such as {% if %}, {% with %} and {% for %} are tested and should run fine.

Jinja2 templates location

IMPORTANT: For Compressor to discover the templates for offline compression, there must be a template loader that implements the get_template_sources method, and is in the TEMPLATE_LOADERS setting.

If you’re using Jinja2, you’re likely to have a Jinja2 template loader in the TEMPLATE_LOADERS setting, otherwise Django won’t know how to load Jinja2 templates.

By default, if you don’t override the TEMPLATE_LOADERS setting, it will include the app directories loader that searches for templates under the templates directory in each app. If the app directories loader is in use and your Jinja2 templates are in the <app>/templates directories, Compressor will be able to find the Jinja2 templates.

However, if you have Jinja2 templates in other location(s), you could include the filesystem loader (django.template.loaders.filesystem.Loader) in the TEMPLATE_LOADERS setting and specify the custom location in the TEMPLATE_DIRS setting.

Using your custom loader

You should configure TEMPLATE_LOADERS as such:

TEMPLATE_LOADERS = (
    'your_app.Loader',
    ... other loaders (optional) ...
)

You could implement the get_template_sources method in your loader or make use of the Django’s builtin loaders to report the Jinja2 template location(s).