218 lines
7.5 KiB
Plaintext
218 lines
7.5 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>
|
|
|
|
Linked files **must** be accessible via :ref:`COMPRESS_URL <compress_url>`.
|
|
|
|
If the :ref:`COMPRESS_ENABLED <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 :ref:`precompilers <compress_precompilers>`
|
|
setting :ref:`COMPRESS_ENABLED <compress_enabled>` to ``False`` won't
|
|
affect the processing of those files. Only the
|
|
:ref:`CSS <compress_css_filters>` and
|
|
:ref:`JavaScript filters <compress_js_filters>` will be disabled.
|
|
|
|
If both DEBUG and :ref:`COMPRESS_ENABLED <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
|
|
:ref:`COMPRESS_CACHE_BACKEND <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 :ref:`COMPRESS_OFFLINE <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
|
|
:ref:`COMPRESS_OFFLINE_CONTEXT <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 ``MEDIA_URL`` and
|
|
``STATIC_URL`` (if specified in the settings).
|
|
|
|
The result of running the ``compress`` management command will be cached
|
|
in a file called ``manifest.json`` using the :ref:`configured storage
|
|
<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``
|
|
Always "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``", this will contain a "``url``" key that maps to
|
|
the relative URL for the compressed asset.
|
|
|
|
If ``type`` is "``css``", 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['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
|
|
---------
|
|
|
|
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.
|