@@ -39,35 +51,88 @@ The basic syntax for specifying CSS/JavaScript groups files is ::
Group options
-------------
* ``source_filenames`` is a tuple with the source files to be compressed.
The files are concatenated in the order it is specified in the tuple. This option is required.
* ``output_filename`` is the filename of the (to be) compressed file. This option is required.
* ``extra_context`` is a dictionary of values to add to the template context,
``source_filenames``
....................
**Required**
Is a tuple with the source files to be compressed.
The files are concatenated in the order it is specified in the tuple.
``output_filename``
...................
**Required**
Is the filename of the (to be) compressed file.
``extra_context``
.................
**Optionnal**
Is a dictionary of values to add to the template context,
when generating the HTML for the HTML-tags with the templatetags.
This option is not required and can be left out.
For CSS, if you do not specify ``extra_context``/``media``, the default media in
the ``<link>`` output will be ``media="all"``.
Note that all filenames are specified relative to ``COMPRESS_ROOT``, and thus the source
files needs to be in your ``COMPRESS_ROOT``.
.. note::
Note that all filenames are specified relative to ``COMPRESS_ROOT``, and thus the source
files needs to be in your ``COMPRESS_ROOT``.
Other settings
--------------
* ``COMPRESS``: When ``COMPRESS`` is ``True``, CSS and JavaScripts will be concatenated and filtered.
``COMPRESS``
............
When ``COMPRESS`` is ``True``, CSS and JavaScripts will be concatenated and filtered.
When ``False``, the source-files will be used instead.
Defaults to ``not DEBUG`` (compressed files will only be used in non-DEBUG-mode (production))
* ``COMPRESS_AUTO``: Auto-generate CSS and JavaScript files whenever needed,
when the template tags are invoked.
Defaults to ``not DEBUG`` (compressed files will only be used when ``DEBUG`` is ``False``)
``COMPRESS_AUTO``
.................
Auto-generate CSS and JavaScript files whenever needed, when the template tags
are invoked.
This setting will make sure that the outputted files always are up to date
(assuming that you are using the provided templatetags to output the links to
your files).
If you disable this, you can use the management command to keep your files
manually updated. Defaults to ``True``.
* ``COMPRESS_VERSION``: Regulates whether or not to add a "version number" to the outputted files filename with for use with “far future Expires”. For more information, see [FarFutureExpires]. When you specify ``COMPRESS_VERSION`` you will also need to add a placeholder (which by default is '?') for the version number in the ``output_filename`` setting.
* ``COMPRESS_VERSION_REMOVE_OLD``: When ``True``, old compressed files will be removed when new versions are generated. All files with a matching name e.g. ``output_filename`` where ? can be replaced by digits will be removed. If you for some reason have files named in the same way, you should consider moving them or putting the compressed files in their own directory. Defaults to ``True``.
manually updated.
Defaults to ``True``.
``COMPRESS_VERSION``
....................
Regulates whether or not to add a "version number" to the outputted files
filename with for use with “far future Expires”.
For more information, see :doc:`farfutureexpires`.
When you specify ``COMPRESS_VERSION`` you will also need to add a placeholder
(which by default is ``?``) for the version number in the ``output_filename`` setting.
``COMPRESS_VERSION_REMOVE_OLD``
...............................
``COMPRESS_VERSION`` example::
When ``True``, old compressed files will be removed when new versions are generated.
All files with a matching name e.g. ``output_filename`` where ``?`` can be replaced
by digits will be removed.
If you for some reason have files named in the same way, you should consider moving
them or putting the compressed files in their own directory.
Defaults to ``True``.
Example::
COMPRESS = True
COMPRESS_VERSION = True
...
...
@@ -82,48 +147,37 @@ Other settings
},
}
This will output a file like ``/media/c/screen.r1213947531.css``, which will be re-generated and updated when you change your source files.
This will output a file like ``/media/c/screen.r1213947531.css``,
which will be re-generated and updated when you change your source files.
* ``COMPRESS_CSS_COMPRESSORS``: A tuple of filters to be applied to CSS files.
Defaults to ``('compress.compressors.yui.YUICompressor', )``.
* ``COMPRESS_JS_COMPRESSORS``: A tuple of filters to be applied to JavaScript files.
Defaults to ``('compress.compressors.yui.YUICompressor',)``
``COMPRESS_CSS_COMPRESSORS``
............................
.. note::
A tuple of compressors to be applied to CSS files.
Please note that in order to use YUI Compressor, you need to install YUI Compressor (see :doc:`ìnstallation` for more details).
Defaults to ``('compress.compressors.yui.YUICompressor',)``.
``COMPRESS_*_COMPRESSORS`` can be set to an empty tuple or None to not use any filters.
The files will however still be concatenated to one file.
``COMPRESS_JS_COMPRESSORS``
...........................
Prefix - An Alternative to MEDIA_URL
------------------------------------
A tuple of compressors to be applied to JavaScript files.
In cases where you want to deploy your compiled script and styles to somewhere
other than your MEDIA_URL, say a Content Delivery Network,
you can use the optional ``prefix`` parameter::
Defaults to ``('compress.compressors.yui.YUICompressor',)``
There are several ways for generating version strings. Basically, two types are available.
These are: mtime version strings and hash version strings.
mtime version strings (default)
===============================
Modification time version
=========================
This is the default method for generating version strings. In short, when invoked, it checks whether any of the source files system timestamps (mtime) is newer than the version string of the corresponding compressed file. If that is the case, the compressed output file version string will be the mtime of the most recent source file.
hash version strings
====================
Hash version
============
Hash-based versioning works by generating a hash string based on the contents of the source files. Available hash-based versioning methods are MD5 and SHA-1.
MD5 version strings
-------------------
MD5 version
-----------
To generate MD5 version strings, put this in your `settings.py` ::
