521 lines
17 KiB
Plaintext
521 lines
17 KiB
Plaintext
.. _settings:
|
|
|
|
Settings
|
|
========
|
|
|
|
.. currentmodule:: django.conf.settings
|
|
|
|
Django Compressor has a number of settings that control its behavior.
|
|
They've been given sensible defaults.
|
|
|
|
Base settings
|
|
-------------
|
|
|
|
.. attribute:: 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
|
|
:attr:`~django.conf.settings.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>
|
|
|
|
.. attribute:: COMPRESS_URL
|
|
|
|
:Default: ``STATIC_URL``
|
|
|
|
Controls the URL that linked files will be read from and compressed files
|
|
will be written to.
|
|
|
|
.. attribute:: COMPRESS_ROOT
|
|
|
|
:Default: ``STATIC_ROOT``
|
|
|
|
Controls the absolute file path that linked static will be read from and
|
|
compressed static will be written to when using the default
|
|
:attr:`~django.conf.settings.COMPRESS_STORAGE`
|
|
``compressor.storage.CompressorFileStorage``.
|
|
|
|
.. attribute:: COMPRESS_OUTPUT_DIR
|
|
|
|
:Default: ``'CACHE'``
|
|
|
|
Controls the directory inside :attr:`~django.conf.settings.COMPRESS_ROOT`
|
|
that compressed files will be written to.
|
|
|
|
Backend settings
|
|
----------------
|
|
|
|
.. attribute:: COMPRESS_CSS_FILTERS
|
|
|
|
:default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
|
|
|
|
A list of filters that will be applied to CSS.
|
|
|
|
Possible options are (including their settings):
|
|
|
|
- ``compressor.filters.css_default.CssAbsoluteFilter``
|
|
|
|
A filter that normalizes the URLs used in ``url()`` CSS statements.
|
|
|
|
.. attribute:: COMPRESS_CSS_HASHING_METHOD
|
|
|
|
The method to use when calculating the suffix to append to URLs in
|
|
your processed CSS files. Either ``None``, ``'mtime'`` (default) or
|
|
``'content'``. Use the ``None`` if you want to completely disable that
|
|
feature, and the ``'content'`` in case you're using multiple servers
|
|
to serve your content.
|
|
|
|
- ``compressor.filters.datauri.CssDataUriFilter``
|
|
|
|
A filter for embedding media as `data: URIs`_ in the CSS.
|
|
|
|
.. attribute:: COMPRESS_DATA_URI_MAX_SIZE
|
|
|
|
Only files that are smaller than this in bytes value will be embedded.
|
|
|
|
- ``compressor.filters.yui.YUICSSFilter``
|
|
|
|
A filter that passes the CSS content to the `YUI compressor`_.
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: COMPRESS_YUI_CSS_ARGUMENTS
|
|
|
|
The arguments passed to the compressor.
|
|
|
|
- ``compressor.filters.yuglify.YUglifyCSSFilter``
|
|
|
|
A filter that passes the CSS content to the `yUglify compressor`_.
|
|
|
|
.. attribute:: COMPRESS_YUGLIFY_BINARY
|
|
|
|
The yUglify compressor filesystem path.
|
|
|
|
.. attribute:: COMPRESS_YUGLIFY_CSS_ARGUMENTS
|
|
|
|
The arguments passed to the compressor. Defaults to --terminal.
|
|
|
|
.. _csscompressor_filter:
|
|
|
|
- ``compressor.filters.cssmin.CSSCompressorFilter``
|
|
|
|
A filter that uses Yury Selivanov's Python port of the YUI CSS compression
|
|
algorithm csscompressor_.
|
|
|
|
- ``compressor.filters.cssmin.rCSSMinFilter``
|
|
|
|
A filter that uses the cssmin implementation rCSSmin_ to compress CSS
|
|
(installed by default).
|
|
|
|
- ``compressor.filters.cleancss.CleanCSSFilter``
|
|
|
|
A filter that passes the CSS content to the `clean-css`_ tool.
|
|
|
|
.. attribute:: COMPRESS_CLEAN_CSS_BINARY
|
|
|
|
The clean-css binary filesystem path.
|
|
|
|
.. attribute:: COMPRESS_CLEAN_CSS_ARGUMENTS
|
|
|
|
The arguments passed to clean-css.
|
|
|
|
|
|
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
|
|
.. _csscompressor: http://pypi.python.org/pypi/csscompressor/
|
|
.. _rCSSmin: http://opensource.perlig.de/rcssmin/
|
|
.. _`clean-css`: https://github.com/GoalSmashers/clean-css/
|
|
|
|
|
|
- ``compressor.filters.template.TemplateFilter``
|
|
|
|
A filter that renders the CSS content with Django templating system.
|
|
|
|
.. attribute:: COMPRESS_TEMPLATE_FILTER_CONTEXT
|
|
|
|
The context to render your css files with.
|
|
|
|
|
|
.. _compress_js_filters:
|
|
|
|
.. attribute:: 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 (installed by default).
|
|
|
|
.. _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`_.
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: 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`_.
|
|
|
|
.. attribute:: COMPRESS_YUI_BINARY
|
|
|
|
The YUI compressor filesystem path.
|
|
|
|
.. attribute:: COMPRESS_YUI_JS_ARGUMENTS
|
|
|
|
The arguments passed to the compressor.
|
|
|
|
- ``compressor.filters.yuglify.YUglifyJSFilter``
|
|
|
|
A filter that passes the JavaScript code to the `yUglify compressor`_.
|
|
|
|
.. attribute:: COMPRESS_YUGLIFY_BINARY
|
|
|
|
The yUglify compressor filesystem path.
|
|
|
|
.. attribute:: COMPRESS_YUGLIFY_JS_ARGUMENTS
|
|
|
|
The arguments passed to the compressor.
|
|
|
|
- ``compressor.filters.template.TemplateFilter``
|
|
|
|
A filter that renders the JavaScript code with Django templating system.
|
|
|
|
.. attribute:: COMPRESS_TEMPLATE_FILTER_CONTEXT
|
|
|
|
The context to render your JavaScript code with.
|
|
|
|
.. _rJSmin: http://opensource.perlig.de/rjsmin/
|
|
.. _`Google Closure compiler`: http://code.google.com/closure/compiler/
|
|
.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/
|
|
.. _`yUglify compressor`: https://github.com/yui/yuglify
|
|
.. _`Slim It`: https://github.com/rspivak/slimit
|
|
|
|
.. attribute:: 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 or filter specified as the second
|
|
item:
|
|
|
|
#. mimetype
|
|
The mimetype of the file or inline code that should be compiled.
|
|
|
|
#. command_or_filter
|
|
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.
|
|
|
|
Alternatively, you may provide the fully qualified class name of a
|
|
filter you wish to use as a precompiler.
|
|
|
|
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}'),
|
|
('text/stylus', 'stylus < {infile} > {outfile}'),
|
|
('text/foobar', 'path.to.MyPrecompilerFilter'),
|
|
)
|
|
|
|
.. note::
|
|
Depending on the implementation, some precompilers might not support
|
|
outputting to something else than ``stdout``, so you'll need to omit the
|
|
``{outfile}`` parameter when working with those. For instance, if you
|
|
are using the Ruby version of lessc, you'll need to set up the
|
|
precompiler like this::
|
|
|
|
('text/less', 'lessc {infile}'),
|
|
|
|
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://coffeescript.org/
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: 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.
|
|
|
|
Caching settings
|
|
----------------
|
|
|
|
.. attribute:: COMPRESS_CACHE_BACKEND
|
|
|
|
:Default: ``CACHES["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.
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: 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
|
|
:attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT`.
|
|
|
|
.. attribute:: COMPRESS_MTIME_DELAY
|
|
|
|
:Default: ``10``
|
|
|
|
The amount of time (in seconds) to cache the modification timestamp of a
|
|
file. Should be smaller than
|
|
:attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT` and
|
|
:attr:`~django.conf.settings.COMPRESS_MINT_DELAY`.
|
|
|
|
.. attribute:: COMPRESS_CACHEABLE_PRECOMPILERS
|
|
|
|
:Default: ``()``
|
|
|
|
An iterable of precompiler mimetypes as defined in :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS`
|
|
for which the compiler output can be cached based solely on the contents
|
|
of the input file. This lets Django Compressor avoid recompiling unchanged
|
|
files. Caching is appropriate for compilers such as CoffeeScript where files
|
|
are compiled one-to-one, but not for compilers such as SASS that have an
|
|
``import`` mechanism for including one file from another. If caching is enabled
|
|
for such a compiler, Django Compressor will not know to recompile files when a file
|
|
they import is modified.
|
|
|
|
.. attribute:: 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
|
|
|
|
.. attribute:: COMPRESS_CACHE_KEY_FUNCTION
|
|
|
|
:Default: ``'compressor.cache.simple_cachekey'``
|
|
|
|
The function to use when generating the cache key. The function must take
|
|
one argument which is the partial key based on the source's hex digest.
|
|
It must return the full key as a string.
|
|
|
|
Offline settings
|
|
----------------
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: COMPRESS_OFFLINE_CONTEXT
|
|
|
|
:Default: ``{'STATIC_URL': settings.STATIC_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.
|
|
|
|
.. note::
|
|
|
|
It is also possible to perform offline compression for multiple
|
|
contexts by providing a list or tuple of dictionaries, or by providing
|
|
a dotted string pointing to a generator function.
|
|
|
|
This makes it easier to generate contexts dynamically for situations
|
|
where a user might be able to select a different theme in their user
|
|
profile, or be served different stylesheets based on other criteria.
|
|
|
|
An example of multiple offline contexts by providing a list or tuple::
|
|
|
|
# project/settings.py:
|
|
COMPRESS_OFFLINE_CONTEXT = [
|
|
{'THEME': 'plain', 'STATIC_URL': STATIC_URL},
|
|
{'THEME': 'fancy', 'STATIC_URL': STATIC_URL},
|
|
# ...
|
|
]
|
|
|
|
An example of multiple offline contexts generated dynamically::
|
|
|
|
# project/settings.py:
|
|
COMPRESS_OFFLINE_CONTEXT = 'project.module.offline_context'
|
|
|
|
# project/module.py:
|
|
from django.conf import settings
|
|
def offline_context():
|
|
from project.models import Company
|
|
for theme in set(Company.objects.values_list('theme', flat=True)):
|
|
yield {'THEME': theme, 'STATIC_URL': settings.STATIC_URL}
|
|
|
|
.. attribute:: COMPRESS_OFFLINE_MANIFEST
|
|
|
|
:Default: ``manifest.json``
|
|
|
|
The name of the file to be used for saving the names of the files
|
|
compressed offline.
|