Usage

{% load compress %}
{% compress <js/css> [<file/inline> [block_name]] %}
<html of inline or linked JS/CSS>
{% endcompress %}

Examples

Basic example:

{% 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:

<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:

{% 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:

<script type="text/javascript" charset="utf-8">
obj = {};
obj.value = "value";
</script>

Specifying a block_name will change the output filename. It can also be accessed in the post_compress signal in the context parameter.

{% 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:

<script type="text/javascript" src="/static/CACHE/js/base.3f33b9146e12.js" charset="utf-8"></script>

Note

Remember that django-compressor will try to group outputs by media.

Linked files must be accessible via COMPRESS_URL.

If the 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 precompilers, setting COMPRESS_ENABLED to False won’t affect the processing of those files. Only the COMPRESS_FILTERS will be disabled.

If both DEBUG and 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 COMPRESS_CACHE_BACKEND and Django’s caching documentation).

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 Behind the Scenes for details). This results in better performance and enables certain deployment scenarios (see Common Deployment Scenarios).

To use offline compression, enable the 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 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.:

{% 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 configured storage to be able to be transferred from your development computer to the server easily.

Signals

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 compressor.css.CssCompressor or compressor.js.JsCompressor.

Changed in version 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

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.