1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
Jinja2 In-Request Support
=========================
Django Compressor comes with support for Jinja2_ via an extension.
Plain Jinja2
------------
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})
Jinja2 Offline Compression Support
==================================
You'd 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.
Usage
-----
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).
A typical usage could be :
- ``./manage.py compress`` for processing Django templates first, skipping
Jinja2 templates.
- ``./manage.py compress --engine jinja2`` for processing Jinja2 templates,
skipping Django templates.
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/
|
