235 lines
8.0 KiB
Plaintext
235 lines
8.0 KiB
Plaintext
.. _usage:
|
|
|
|
Usage
|
|
=====
|
|
|
|
.. code-block:: django
|
|
|
|
{% load compress %}
|
|
{% compress <js/css> [<file/inline> [block_name]] %}
|
|
<html of inline or linked JS/CSS>
|
|
{% endcompress %}
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. code-block:: django
|
|
|
|
{% load compress %}
|
|
|
|
{% 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 %}
|
|
|
|
Which would be rendered something like:
|
|
|
|
.. code-block:: django
|
|
|
|
<link rel="stylesheet" href="/static/CACHE/css/f7c661b7a124.css" type="text/css" charset="utf-8">
|
|
|
|
or:
|
|
|
|
.. code-block:: django
|
|
|
|
{% load compress %}
|
|
|
|
{% compress js %}
|
|
<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 %}
|
|
|
|
Which would be rendered something like:
|
|
|
|
.. code-block:: django
|
|
|
|
<script type="text/javascript" src="/static/CACHE/js/3f33b9146e12.js" charset="utf-8"></script>
|
|
|
|
.. note::
|
|
|
|
Remember that django-compressor will try to :ref:`group ouputs 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:`CSS <django.conf.settings.COMPRESS_CSS_FILTERS>` and
|
|
:attr:`JavaScript filters <django.conf.settings.COMPRESS_JS_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`_).
|
|
|
|
The compress template tag supports a second argument specifying the output
|
|
mode and defaults to saving the result in a file. Alternatively you can
|
|
pass '``inline``' to the template tag to return the content directly to the
|
|
rendered page, e.g.:
|
|
|
|
.. code-block:: django
|
|
|
|
{% load compress %}
|
|
|
|
{% 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 %}
|
|
|
|
would be rendered something like::
|
|
|
|
<script type="text/javascript" charset="utf-8">
|
|
obj = {};
|
|
obj.value = "value";
|
|
</script>
|
|
|
|
The compress template tag also supports a third argument for naming the output
|
|
of that particular compress tag. This is then added to the context so you can
|
|
access it in the `post_compress signal <signals>`.
|
|
|
|
.. _memcached: http://memcached.org/
|
|
.. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached
|
|
|
|
.. _pre-compression:
|
|
|
|
Pre-compression
|
|
---------------
|
|
|
|
Django Compressor comes with an optional ``compress`` management command to
|
|
run the compression outside of the request/response loop -- independent
|
|
from user requests. This allows to pre-compress CSS and JavaScript files and
|
|
works just like the automatic compression with the ``{% compress %}`` tag.
|
|
|
|
To compress the files "offline" and update the offline cache you have
|
|
to use the ``compress`` management command, ideally during deployment.
|
|
Also make sure to enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
|
|
setting. In case you don't use the ``compress`` management command, Django
|
|
Compressor will automatically fallback to the automatic compression using
|
|
the template tag.
|
|
|
|
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 src="{{ path_to_files }}js/one.js" type="text/javascript" charset="utf-8"></script>
|
|
{% endcompress %}
|
|
|
|
Since this template requires a variable (``path_to_files``) you need to
|
|
specify this in your settings before using the ``compress`` management
|
|
command::
|
|
|
|
COMPRESS_OFFLINE_CONTEXT = {
|
|
'path_to_files': '/static/js/',
|
|
}
|
|
|
|
If not specified, the ``COMPRESS_OFFLINE_CONTEXT`` will by default contain
|
|
the commonly used setting to refer to saved files ``STATIC_URL``.
|
|
|
|
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 transfered from your developement
|
|
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.
|