deb-python-django-compressor/docs/settings.txt

.. _settings:

Settings
--------

Django Compressor has a number of settings that control its behavior.
They've been given sensible defaults.

.. _compress:

COMPRESS
^^^^^^^^

:Default: the opposite of ``DEBUG``

Boolean that decides if compression will happen.

.. _compress_url:

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 or empty, e.g. on older Django versions (<1.3).

.. _compress_root:

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 when using the default COMPRESS_STORAGE_
``compressor.storage.CompressorFileStorage``.

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

COMPRESS_PRECOMPILERS
^^^^^^^^^^^^^^^^^^^^^

:Default: ``()``

An iterable of two-tuples whose first item is the mimetype of the files or
hunks you want to compile with the command specified as the second item:

#. mimetype
    The mimetype of the file or inline code should that should be compiled.

#. command
    The command to call on each of the files. Modern Python string
    formatting will be provided for the two placeholders ``{infile}`` and
    ``{outfile}`` whose existence in the command string also triggers the
    actual creation of those temporary files. If not given in the command
    string, Django Compressor will use ``stdin`` and ``stdout`` respectively
    instead.

Example::

    COMPRESS_PRECOMPILERS = (
        ('text/coffeescript', 'coffee --compile --stdio'),
        ('text/less', 'lessc {infile} {outfile}'),
        ('text/x-sass', 'sass {infile} {outfile}'),
        ('text/x-scss', 'sass --scss {infile} {outfile}'),
    )

With that setting (and CoffeeScript_ installed), you could add the following
code to your templates:

.. code-block:: django

    {% load compress %}

    {% compress js %}
    <script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
    <script type="text/coffeescript" charset="utf-8">
    # Functions:
    square = (x) -> x * x
    </script>
    {% endcompress %}

This would give you something like this::

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

The same works for less_, too:

.. code-block:: django

    {% load compress %}

    {% compress css %}
    <link type="text/less" rel="stylesheet" href="/static/css/styles.less" charset="utf-8">
    <style type="text/less">
    @color: #4D926F;

    #header {
      color: @color;
    }
    </style>
    {% endcompress %}

Which would be rendered something like::

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

.. _less: http://lesscss.org/
.. _CoffeeScript: http://jashkenas.github.com/coffee-script/

.. _compress_storage:

COMPRESS_STORAGE
^^^^^^^^^^^^^^^^

:Default: ``'compressor.storage.CompressorFileStorage'``

The dotted path to a Django Storage backend to be used to save the
compressed files.

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

COMPRESS_PARSER
^^^^^^^^^^^^^^^

:Default: ``'compressor.parser.BeautifulSoupParser'``

The backend to use when parsing the JavaScript or Stylesheet files.
The backends included in Django Compressor:

- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.LxmlParser``

See :ref:`dependencies` for more info about the packages you need
for each parser.

.. _compress_cache_backend:

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

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_DEBUG_TOGGLE
^^^^^^^^^^^^^^^^^^^^^

:Default: None

The name of the GET variable that toggles the debug mode and prevents Django
Compressor from performing the actual compression. Only useful for debugging.

.. warning::

    Don't use this option in production!

    An easy convention is to only set it depending on the ``DEBUG`` setting::

        if DEBUG:
            COMPRESS_DEBUG_TOGGLE = 'whatever'

.. note::

    This only works for pages that are rendered using the RequestContext_
    and the ``django.core.context_processors.request`` context processor.

.. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext

.. _compress_offline:

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.

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

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.