Usage

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

Examples

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

<link rel="stylesheet" href="/static/CACHE/css/f7c661b7a124.css" type="text/css" charset="utf-8">

or:

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

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

Note

Remember that django-compressor will try to group ouputs 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 CSS and JavaScript 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).

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

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

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 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 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 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 configured storage to be able to be transfered from your developement 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.