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

COMPRESS_ENABLED
^^^^^^^^^^^^^^^^

:Default: the opposite of ``DEBUG``

Boolean that decides if compression will happen. To test compression
when ``DEBUG`` is ``True`` COMPRESS_ENABLED_ must also be set to ``True``.

When COMPRESS_ENABLED_ is ``False`` the input will be rendered without any
compression except for code with a mimetype matching one listed in the
COMPRESS_PRECOMPILERS_ setting. These matching files are still passed to the
precompiler before rendering. 

An example for some javascript and coffeescript.

.. code-block:: django

    {% load compress %}

    {% compress js %}
    <script type="text/javascript" src="/static/js/site-base.js" />
    <script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
    {% endcompress %}

With COMPRESS_ENABLED_ set to ``False`` this would give you something like
this::

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



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

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.

- ``COMPRESS_CSS_HASHING_METHOD`` -- The method to use when calculating
  the hash to append to processed URLs. Either ``'mtime'`` (default) or
  ``'content'``. Use the latter in case you're using multiple server to
  serve your static files.

``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_MAX_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. Make sure
  to also prepend this setting with ``java -jar`` if you use that kind of
  distribution.

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

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

.. _compress_js_filters:

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.

.. _slimit_filter:

``compressor.filters.jsmin.SlimItFilter``
"""""""""""""""""""""""""""""""""""""""""

A filter that uses the jsmin implementation `Slim It`_ to compress JavaScript code.

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

A filter that uses `Google Closure compiler`_.

- ``COMPRESS_CLOSURE_COMPILER_BINARY`` -- The Closure compiler filesystem
  path. Make sure to also prepend this setting with ``java -jar`` if you
  use that kind of distribution.

- ``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/
.. _`Slim It`: http://slimit.org/

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

.. warning::

    In some cases the ``compressor.parser.HtmlParser`` parser isn't able to
    parse invalid HTML in JavaScript or CSS content. As a workaround you
    should use one of the more forgiving parsers, e.g. the
    ``BeautifulSoupParser``.

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.

If available, the ``STATIC_URL`` setting is also added to the context.

.. _compress_offline_manifest:

COMPRESS_OFFLINE_MANIFEST
^^^^^^^^^^^^^^^^^^^^^^^^^

:Default: ``manifest.json``

The name of the file to be used for saving the names of the files compressed
offline.