332 lines
9.9 KiB
Plaintext
332 lines
9.9 KiB
Plaintext
Django compressor
|
|
=================
|
|
|
|
Compresses linked and inline JavaScript or CSS into a single cached file.
|
|
|
|
Syntax
|
|
------
|
|
|
|
.. code-block:: django
|
|
|
|
{% load compress %}
|
|
{% compress <js/css> %}
|
|
<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 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: http://memcached.org/
|
|
.. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached
|
|
|
|
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.
|
|
|
|
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 settings.py. 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.
|
|
|
|
**Flexibility**
|
|
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.
|
|
|
|
Settings
|
|
--------
|
|
|
|
Django compressor has a number of settings that control its behavior.
|
|
They've been given sensible defaults.
|
|
|
|
COMPRESS
|
|
^^^^^^^^
|
|
|
|
:Default: the opposite of ``DEBUG``
|
|
|
|
Boolean that decides if compression will happen.
|
|
|
|
COMPRESS_URL
|
|
^^^^^^^^^^^^
|
|
|
|
: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).
|
|
|
|
COMPRESS_ROOT
|
|
^^^^^^^^^^^^^
|
|
|
|
: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).
|
|
|
|
COMPRESS_OUTPUT_DIR
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
:Default: ``'cache'``
|
|
|
|
Controls the directory inside COMPRESS_ROOT_ that compressed files will
|
|
be written to.
|
|
|
|
COMPRESS_CSS_FILTERS
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
|
|
|
|
A list of filters that will be applied to CSS.
|
|
|
|
COMPRESS_JS_FILTERS
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
:Default: ``['compressor.filters.jsmin.JSMinFilter']``
|
|
|
|
A list of filters that will be applied to javascript.
|
|
|
|
COMPRESS_STORAGE
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
:Default: ``'compressor.storage.CompressorFileStorage'``
|
|
|
|
The dotted path to a Django Storage backend to be used to save the
|
|
compressed files.
|
|
|
|
``compressor`` ships with one additional storage backend:
|
|
|
|
* ``'compressor.storage.GzipCompressorFileStorage'``
|
|
|
|
A subclass of the default storage backend, which will additionally
|
|
create ``*.gz`` files of each of the compressed files.
|
|
|
|
COMPRESS_PARSER
|
|
^^^^^^^^^^^^^^^
|
|
|
|
: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.
|
|
|
|
COMPRESS_CACHE_BACKEND
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
: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.
|
|
|
|
COMPRESS_REBUILD_TIMEOUT
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
: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.
|
|
|
|
COMPRESS_MINT_DELAY
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
: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_.
|
|
|
|
COMPRESS_MTIME_DELAY
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
: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_
|
|
and COMPRESS_MINT_DELAY_.
|
|
|
|
COMPRESS_OFFLINE
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
: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_.
|
|
|
|
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.
|
|
|
|
COMPRESS_OFFLINE_CONTEXT
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
: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
|
|
command::
|
|
|
|
COMPRESS_OFFLINE_CONTEXT = {
|
|
'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.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
* 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: http://www.crummy.com/software/BeautifulSoup/
|
|
.. _lxml: http://codespeak.net/lxml/
|
|
.. _libxml2: http://xmlsoft.org/
|