/
usage.txt
239 lines (166 loc) · 7.99 KB
/
usage.txt
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
.. _usage:
Usage
=====
.. code-block:: django
{% load compress %}
{% compress <js/css> [<file/inline/preload> [block_name]] %}
<html of inline or linked JS/CSS>
{% endcompress %}
Examples
--------
Basic example:
.. code-block:: django
{% compress css %}
<link rel="stylesheet" href="/static/css/one.css" type="text/css" charset="utf-8">
<style type="text/css">p { border:5px solid green;}</style>
<link rel="stylesheet" href="/static/css/two.css" type="text/css" charset="utf-8">
{% endcompress %}
Result:
.. code-block:: django
<link rel="stylesheet" href="/static/CACHE/css/output.f7c661b7a124.css" type="text/css" charset="utf-8">
Adding the ``inline`` parameter will put the content directly to the
rendered page instead of a file:
.. code-block:: django
{% compress js inline %}
<script src="/static/js/one.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">obj.value = "value";</script>
{% endcompress %}
Result:
.. code-block:: django
<script type="text/javascript" charset="utf-8">
obj = {};
obj.value = "value";
</script>
Adding the ``preload`` parameter will generate the preload tag for the compressed resource in the template:
.. code-block:: django
{% compress js preload %}
<script src="/static/js/one.js" type="text/javascript" charset="utf-8"></script>
{% endcompress %}
Result:
.. code-block:: django
<link rel="preload" href="/static/CACHE/js/d01466eb4fc6.js" as="script" />
Specifying a ``block_name`` will change the output filename. It can also be
accessed in the :ref:`post_compress signal <signals>` in the ``context`` parameter.
.. code-block:: django
{% compress js file base %}
<script src="/static/js/one.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">obj.value = "value";</script>
{% endcompress %}
Result:
.. code-block:: django
<script type="text/javascript" src="/static/CACHE/js/base.3f33b9146e12.js" charset="utf-8"></script>
.. note::
Remember that django-compressor will try to :ref:`group outputs by media <css_notes>`.
Linked files **must** be accessible via
:attr:`~django.conf.settings.COMPRESS_URL`.
If the :attr:`~django.conf.settings.COMPRESS_ENABLED` setting is ``False``
(defaults to the opposite of DEBUG) the ``compress`` template tag does nothing
and simply returns exactly what it was given.
.. note::
If you've configured any
:attr:`precompilers <django.conf.settings.COMPRESS_PRECOMPILERS>`,
setting :attr:`~django.conf.settings.COMPRESS_ENABLED` to ``False`` won't
affect the processing of those files. Only the
:attr:`~django.conf.settings.COMPRESS_FILTERS`
will be disabled.
If both DEBUG and :attr:`~django.conf.settings.COMPRESS_ENABLED` are set to
``True``, incompressible files (off-site or non existent) will throw an
exception. If DEBUG is ``False`` these files will be silently stripped.
.. warning::
For production sites it is **strongly recommended** to use a real cache
backend such as memcached_ to speed up the checks of compressed files.
Make sure you set your Django cache backend appropriately (also see
:attr:`~django.conf.settings.COMPRESS_CACHE_BACKEND` and
Django's `caching documentation`_).
.. _memcached: http://memcached.org/
.. _caching documentation: https://docs.djangoproject.com/en/2.1/topics/cache/#memcached
.. _offline_compression:
Offline Compression
-------------------
Django Compressor has the ability to run the compression "offline",
i.e. outside of the request/response loop -- independent from user requests.
If offline compression is enabled, no new files are generated during a request
and the ``{% compress %}`` tag simply inserts links to the files in the
offline cache (see :ref:`behind_the_scenes` for details). This results in better
performance and enables certain deployment scenarios (see :ref:`scenarios`).
To use offline compression, enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
setting and then run the ``compress`` management command to compress your assets
and update the offline cache.
The command parses all templates that can be found with the template
loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for
``{% compress %}`` blocks. It then will use the context as defined in
:attr:`django.conf.settings.COMPRESS_OFFLINE_CONTEXT` to render its
content. So if you use any variables inside the ``{% compress %}`` blocks,
make sure to list all values you require in ``COMPRESS_OFFLINE_CONTEXT``.
It's similar to a template context and should be used if a variable is used
in the blocks, e.g.:
.. code-block:: django
{% load compress %}
{% compress js %}
<script type="text/javascript">
alert("{{ greeting }}");
</script>
{% endcompress %}
Since this template requires a variable (``greeting``) you need to specify
this in your settings before using the ``compress`` management command::
COMPRESS_OFFLINE_CONTEXT = {
'greeting': 'Hello there!',
}
The result of running the ``compress`` management command will be cached
in a file called ``manifest.json`` using the :attr:`configured storage
<django.conf.settings.COMPRESS_STORAGE>` to be able to be transferred from your development
computer to the server easily.
.. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders
.. _signals:
Signals
-------
.. function:: compressor.signals.post_compress(sender, type, mode, context)
Django Compressor includes a ``post_compress`` signal that enables you to
listen for changes to your compressed CSS/JS. This is useful, for example, if
you need the exact filenames for use in an HTML5 manifest file. The signal
sends the following arguments:
``sender``
Either :class:`compressor.css.CssCompressor` or
:class:`compressor.js.JsCompressor`.
.. versionchanged:: 1.2
The sender is now one of the supported Compressor classes for
easier limitation to only one of them, previously it was a string
named ``'django-compressor'``.
``type``
Either "``js``" or "``css``".
``mode``
Either "``file``" or "``inline``".
``context``
The context dictionary used to render the output of the compress template
tag.
If ``mode`` is "``file``" the dictionary named ``compressed`` in the
context will contain a "``url``" key that maps to the relative URL for
the compressed asset.
If ``type`` is "``css``", the dictionary named ``compressed`` in the
context will additionally contain a "``media``" key with a value of
``None`` if no media attribute is specified on the link/style tag and
equal to that attribute if one is specified.
Additionally, ``context['compressed']['name']`` will be the third
positional argument to the template tag, if provided.
.. note::
When compressing CSS, the ``post_compress`` signal will be called once for
every different media attribute on the tags within the ``{% compress %}``
tag in question.
.. _css_notes:
CSS Notes
---------
All relative ``url()`` bits specified in linked CSS files are automatically
converted to absolute URLs while being processed. Any local absolute URLs (those
starting with a ``'/'``) are left alone.
Stylesheets that are ``@import``'d are not compressed into the main file.
They are left alone.
If the media attribute is set on <style> and <link> elements, a separate
compressed file is created and linked for each media value you specified.
This allows the media attribute to remain on the generated link element,
instead of wrapping your CSS with @media blocks (which can break your own
@media queries or @font-face declarations). It also allows browsers to avoid
downloading CSS for irrelevant media types.
Recommendations
---------------
* Use only relative or full domain absolute URLs in your CSS files.
* Avoid @import! Simply list all your CSS files in the HTML, they'll be combined anyway.