jinja2.txt

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



.. _Jinja2: http://jinja.pocoo.org/docs/