.. _usage:

Usage
=====

.. code-block:: django

    {% load compress %}
    {% compress <js/css> [<file/inline> [block_name]] %}
    <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>

.. note::

    Remember that django-compressor will try to :ref:`group ouputs by media <css_notes>`.

Linked files **must** be accessible via
:attr:`~django.conf.settings.COMPRESS_URL`.

If the :attr:`~django.conf.settings.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
    :attr:`precompilers <django.conf.settings.COMPRESS_PRECOMPILERS>`
    setting :attr:`~django.conf.settings.COMPRESS_ENABLED` to ``False`` won't
    affect the processing of those files. Only the
    :attr:`CSS <django.conf.settings.COMPRESS_CSS_FILTERS>` and
    :attr:`JavaScript filters <django.conf.settings.COMPRESS_JS_FILTERS>`
    will be disabled.

If both DEBUG and :attr:`~django.conf.settings.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
    :attr:`~django.conf.settings.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.:

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

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

.. _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`` 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 :attr:`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
:attr:`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.:

.. 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 ``STATIC_URL``.

The result of running the ``compress`` management command will be cached
in a file called ``manifest.json`` using the :attr:`configured storage
<django.conf.settings.COMPRESS_STORAGE>` to be able to be transfered from your developement
computer to the server easily.

.. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders

.. _signals:

Signals
-------

.. function:: 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 :class:`compressor.css.CssCompressor` or
    :class:`compressor.js.JsCompressor`.

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

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.
