Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

325 lines (215 sloc) 9.931 kB
Django compressor
Compresses linked and inline JavaScript or CSS into a single cached file.
.. code-block:: django
{% load compress %}
{% compress <js/css> %}
<html of inline or linked JS/CSS>
{% endcompress %}
.. 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">
.. 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 accesible via COMPRESS_URL_. If DEBUG is true off-site
files will throw exceptions. If DEBUG is false they will be silently stripped.
If COMPRESS is ``False`` (defaults to the opposite of DEBUG) the ``compress``
template tag simply returns exactly what it was given, to ease development.
.. 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`_).
.. _memcached:
.. _caching documentation:
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.
* 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.
Why another static file combiner for Django?
Short version: None of them did exactly what I needed.
Long version:
**JS/CSS belong in the templates**
Every static combiner for Django I've seen makes you configure
your static files in your While that works, it doesn't make
sense. Static files are for display. And it's not even an option if your
settings are in completely different repositories and use different deploy
processes from the templates that depend on them.
django_compressor doesn't care if different pages use different combinations
of statics. It doesn't care if you use inline scripts or styles. It doesn't
get in the way.
**Automatic regeneration and cache-foreverable generated output**
Statics are never stale and browsers can be told to cache the output forever.
**Full test suite**
I has one.
Django compressor has a number of settings that control its behavior.
They've been given sensible defaults.
:Default: the opposite of ``DEBUG``
Boolean that decides if compression will happen.
:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions)
Controls the URL that linked files will be read from and compressed files
will be written to.
.. note::
This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL``
is not given, e.g. on older Django versions (<1.3).
:Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions)
Controls the absolute file path that linked static will be read from and
compressed static will be written to.
.. note::
This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT``
is not given, e.g. on older Django versions (<1.3).
:Default: ``'cache'``
Controls the directory inside COMPRESS_ROOT_ that compressed files will
be written to.
:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
A list of filters that will be applied to CSS.
:Default: ``['compressor.filters.jsmin.JSMinFilter']``
A list of filters that will be applied to javascript.
:Default: ``''``
The dotted path to a Django Storage backend to be used to save the
compressed files.
:Default: ``'compressor.parser.BeautifulSoupParser'``
The backend to use when parsing the JavaScript or Stylesheet files.
The backends included in ``compressor``:
- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.LxmlParser``
See `Dependencies`_ for more info about the packages you need for each parser.
:Default: ``"default"`` or ``CACHE_BACKEND``
The backend to use for caching, in case you want to use a different cache
backend for compressor.
If you have set the ``CACHES`` setting (new in Django 1.3),
``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for
the default cache backend. You can set it to a different alias that you have
configured in your ``CACHES`` setting.
If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND``
setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting.
:Default: ``2592000`` (30 days in seconds)
The period of time after which the compressed files are rebuilt even if
no file changes are detected.
This is also used by the ``compress`` management command which pre-compresses
the contents of ``{% compress %}`` template tags in the cache.
:Default: ``30`` (seconds)
The upper bound on how long any compression should take to run. Prevents
dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_.
:Default: ``10``
The amount of time (in seconds) to cache the modification timestamp of a
file. Disabled by default. Should be smaller than COMPRESS_REBUILD_TIMEOUT_
:Default: ``False``
Boolean that decides if compression should also be done 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, e.g. during deployment.
In case you don't use the ``compressor`` management command ``compressor``
will automatically fallback to the automatic compression.
It'll will look in the templates that can be found with the template
loader you specify in ``TEMPLATE_LOADERS`` for ``{% compress %}`` blocks
and use 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_.
The result of running the ``compress`` management command will be saved
in the cache as defined in COMPRESS_CACHE_BACKEND_ for the number of
seconds defined in COMPRESS_OFFLINE_TIMEOUT_.
:Default: ``31536000`` (1 year in seconds)
The period of time with which the ``compress`` management command stores
the pre-compressed the contents of ``{% compress %}`` template tags in
the cache.
:Default: ``{'MEDIA_URL': settings.MEDIA_URL}``
The context to be used by the ``compress`` management command when rendering
the contents of ``{% compress %}`` template tags and saving the result in the
offline cache. 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
'path_to_files': '/static/js/',
If not specified the COMPRESS_OFFLINE_CONTEXT will fall back to contain
the commonly used setting to refer to saved files ``MEDIA_URL``.
For forward compatibility ``compressor`` will also add the ``STATIC_URL``
setting (added in Django 1.3) to the COMPRESS_OFFLINE_CONTEXT_ if it's set.
* BeautifulSoup_ (for the default ``compressor.parser.BeautifulSoupParser``)
pip install BeautifulSoup
* lxml_ (for the optional ``compressor.parser.LxmlParser``, requires libxml2_)
STATIC_DEPS=true pip install lxml
.. _BeautifulSoup:
.. _lxml:
.. _libxml2:
Jump to Line
Something went wrong with that request. Please try again.