Settings¶
Django Compressor has a number of settings that control its behavior. They’ve been given sensible defaults.
Base settings¶
-
django.conf.settings.
COMPRESS_ENABLED
¶ Default: the opposite of DEBUG
Boolean that decides if compression will happen. To test compression when
DEBUG
isTrue
COMPRESS_ENABLED
must also be set toTrue
.When
COMPRESS_ENABLED
isFalse
the input will be rendered without any compression except for code with a mimetype matching one listed in theCOMPRESS_PRECOMPILERS
setting. These matching files are still passed to the precompiler before rendering.An example for some javascript and coffeescript.
{% 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 toFalse
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>
-
django.conf.settings.
COMPRESS_URL
¶ Default: STATIC_URL
Controls the URL that linked files will be read from and compressed files will be written to.
-
django.conf.settings.
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
COMPRESS_STORAGE
compressor.storage.CompressorFileStorage
.
-
django.conf.settings.
COMPRESS_OUTPUT_DIR
¶ Default: 'CACHE'
Controls the directory inside
COMPRESS_ROOT
that compressed files will be written to.
Backend settings¶
-
django.conf.settings.
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.-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_CSSTIDY_BINARY
¶ The CSSTidy binary filesystem path.
-
django.conf.settings.
COMPRESS_CSSTIDY_ARGUMENTS
¶ The arguments passed to CSSTidy.
-
compressor.filters.datauri.CssDataUriFilter
A filter for embedding media as data: URIs in the CSS.
-
django.conf.settings.
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.
-
django.conf.settings.
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.
-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_YUGLIFY_BINARY
¶ The yUglify compressor filesystem path.
-
django.conf.settings.
COMPRESS_YUGLIFY_CSS_ARGUMENTS
¶ The arguments passed to the compressor. Defaults to –terminal.
-
compressor.filters.cssmin.CSSMinFilter
A filter that uses Zachary Voase’s Python port of the YUI CSS compression algorithm cssmin.
compressor.filters.template.TemplateFilter
A filter that renders the CSS content with Django templating system.
-
django.conf.settings.
COMPRESS_TEMPLATE_FILTER_CONTEXT
¶ The context to render your css files with.
-
-
django.conf.settings.
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.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.
-
django.conf.settings.
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.
-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_YUI_BINARY
The YUI compressor filesystem path.
-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_YUGLIFY_BINARY
The yUglify compressor filesystem path.
-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_TEMPLATE_FILTER_CONTEXT
The context to render your JavaScript code with.
-
-
django.conf.settings.
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 usestdin
andstdout
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:
{% 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:
{% 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">
-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_PARSER
¶ Default: 'compressor.parser.AutoSelectParser'
The backend to use when parsing the JavaScript or Stylesheet files. The
AutoSelectParser
picks thelxml
based parser when available, and falls back toHtmlParser
iflxml
is not available.LxmlParser
is the fastest available parser, butHtmlParser
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. theBeautifulSoupParser
.The backends included in Django Compressor:
compressor.parser.AutoSelectParser
compressor.parser.LxmlParser
compressor.parser.HtmlParser
compressor.parser.BeautifulSoupParser
compressor.parser.Html5LibParser
See Dependencies for more info about the packages you need for each parser.
Caching settings¶
-
django.conf.settings.
COMPRESS_CACHE_BACKEND
¶ Default: CACHES["default"]
orCACHE_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 yourCACHES
setting.If you have not set
CACHES
and are using the oldCACHE_BACKEND
setting,COMPRESS_CACHE_BACKEND
defaults to theCACHE_BACKEND
setting.
-
django.conf.settings.
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.
-
django.conf.settings.
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
.
-
django.conf.settings.
COMPRESS_MTIME_DELAY
¶ Default: 10
The amount of time (in seconds) to cache the modification timestamp of a file. Should be smaller than
COMPRESS_REBUILD_TIMEOUT
andCOMPRESS_MINT_DELAY
.
-
django.conf.settings.
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.
-
django.conf.settings.
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¶
-
django.conf.settings.
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.
-
django.conf.settings.
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.
-
django.conf.settings.
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.
-
django.conf.settings.
COMPRESS_OFFLINE_MANIFEST
¶ Default: manifest.json
The name of the file to be used for saving the names of the files compressed offline.