165 lines
5.7 KiB
Plaintext
165 lines
5.7 KiB
Plaintext
.. _usage:
|
|
|
|
Usage
|
|
=====
|
|
|
|
.. code-block:: django
|
|
|
|
{% load compress %}
|
|
{% compress <js/css> [<file/infile>] %}
|
|
<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 :ref:`COMPRESS_URL <compress_url>`.
|
|
|
|
If the :ref:`COMPRESS <compress>` setting is ``False`` (defaults to the
|
|
opposite of DEBUG) the ``compress`` template tag does nothing and simply returns
|
|
exactly what it was given.
|
|
|
|
If both DEBUG and :ref:`COMPRESS <compress>` are set to ``True``, uncompressable
|
|
files (off-site or non existent) will throw and 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 arguemnt 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>
|
|
|
|
.. _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`` mangement 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 saved
|
|
in the cache defined in :ref:`COMPRESS_CACHE_BACKEND <compress_cache_backend>`
|
|
for the number of seconds defined in the
|
|
:ref:`COMPRESS_OFFLINE_TIMEOUT <compress_offline_timeout>` setting.
|
|
|
|
.. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders
|
|
|
|
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.
|