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. In order to test compression
when ``DEBUG`` is enabled COMPRESS needs to explicitly be set to ``True``.

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

Possible options are:

``compressor.filters.css_default.CssAbsoluteFilter``
""""""""""""""""""""""""""""""""""""""""""""""""""""

A filter that normalizes the URLs used in ``url()`` CSS statements.

``compressor.filters.csstidy.CSSTidyFilter``
""""""""""""""""""""""""""""""""""""""""""""

A filter that passes the CSS content to the CSSTidy_ tool.

- ``COMPRESS_CSSTIDY_BINARY`` -- The CSSTidy binary filesystem path.

- ``COMPRESS_CSSTIDY_ARGUMENTS`` -- The arguments passed to CSSTidy.

``compressor.filters.datauri.DataUriFilter``
""""""""""""""""""""""""""""""""""""""""""""

A filter for embedding media as `data: URIs`_ in the CSS.

- ``COMPRESS_DATA_URI_MIN_SIZE`` -- Only files that are smaller than
  this value will be embedded. In bytes.

``compressor.filters.yui.YUICSSFilter``
"""""""""""""""""""""""""""""""""""""""

A filter that passes the CSS content to the `YUI compressor`_.

- ``COMPRESS_YUI_BINARY`` -- The YUI compressor filesystem path.

- ``COMPRESS_YUI_CSS_ARGUMENTS``-- The arguments passed to the compressor.

``compressor.filters.cssmin.CSSMinFilter``
""""""""""""""""""""""""""""""""""""""""""

A filter that uses Zachary Voase's Python port of the YUI CSS compression
algorithm cssmin_.

``compressor.filters.compass.CompassFilter``
""""""""""""""""""""""""""""""""""""""""""""

A filter that runs Compass_'s compile command. **(BETA)**

- ``COMPRESS_COMPASS_BINARY`` -- The compass CLI tool filesystem path.

- ``COMPRESS_COMPASS_ARGUMENTS`` -- The arguments passed to the compass CLI tool.

- ``COMPRESS_COMPASS_PLUGINS`` -- A list of plugins names that are passed to
  compass' require option e.g. ``['my_plugin']`` leads to passing
  ``--require my_plugin``.

.. _CSSTidy: http://csstidy.sourceforge.net/
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _cssmin: http://pypi.python.org/pypi/cssmin/
.. _Compass: http://compass-style.org/


COMPRESS_JS_FILTERS
^^^^^^^^^^^^^^^^^^^

:Default: ``['compressor.filters.jsmin.JSMinFilter']``

A list of filters that will be applied to javascript. Possible options are:

``compressor.filters.jsmin.JSMinFilter``
"""""""""""""""""""""""""""""""""""""""""

A filter that uses the jsmin implementation rJSmin_ to compress JavaScript code.

``compressor.filters.closure.ClosureCompilerFilter``
""""""""""""""""""""""""""""""""""""""""""""""""""""

A filter that uses `Google Closure compiler`_.

- ``COMPRESS_CLOSURE_COMPILER_BINARY`` -- The Closure compiler filesystem path.

- ``COMPRESS_CLOSURE_COMPILER_ARGUMENTS`` -- The arguments passed to the compiler.

``compressor.filters.yui.YUIJSFilter``
""""""""""""""""""""""""""""""""""""""

A filter that passes the JavaScript code to the `YUI compressor`_.

- ``COMPRESS_YUI_BINARY`` -- The YUI compressor filesystem path.

- ``COMPRESS_YUI_JS_ARGUMENTS`` -- The arguments passed to the compressor.

.. _rJSmin: http://opensource.perlig.de/rjsmin/
.. _`Google Closure compiler`: http://code.google.com/closure/compiler/
.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/

.. _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.AutoSelectParser'``

The backend to use when parsing the JavaScript or Stylesheet files. The
``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls
back to ``HtmlParser`` if ``lxml`` is not available.

``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much
slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it
won't be necessary to change the default parser.

The other two included parsers are considerably slower and should only be
used if absolutely necessary.

The backends included in Django Compressor:

- ``compressor.parser.AutoSelectParser``
- ``compressor.parser.LxmlParser``
- ``compressor.parser.HtmlParser``
- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.Html5LibParser``

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.