102 lines
3.6 KiB
Plaintext
102 lines
3.6 KiB
Plaintext
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/
|