bump_filename was broken because a lot of caches does not properly cache files with querystrings. Therefore it is completely rewritten without any thoughts on backwards compatibility, since it was not possible anyways. This changeset also introduces a couple of other changes that could potentially break old code.
* `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, 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"`.
</code>
h4. Group options
* </tt>source_filenames</tt> 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.
* </tt>output_filename</tt> is the filename of the (to be) compressed file. This option is required.
* </tt>extra_context</tt> 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 </tt>extra_context</tt>/</tt>media</tt>, the default media in the </tt><link></tt> output will be </tt>media="all"</tt>.
Note that all filenames are specified relative to MEDIA_ROOT, and thus the source files needs to be in your MEDIA_ROOT.
= Other settings =
* `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. 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. Files with new filenames will be generated if needed, and old outdated files will be removed at the same time. 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.
h3. Other settings
* </tt>COMPRESS</tt>: When </tt>COMPRESS</tt> is </tt>True</tt>, CSS and JavaScripts will be concatenated and filtered. When </tt>False</tt>, the source-files will be used instead. Defaults to </tt>not DEBUG</tt> (compressed files will only be used in non-DEBUG-mode (production))
* </tt>COMPRESS_AUTO</tt>: 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 </tt>True</tt>.
* </tt>COMPRESS_VERSION</tt>: 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 </tt>COMPRESS_VERSION</tt> you will also need to add a placeholder (which by default is '?') for the version number in the </tt>output_filename</tt> setting. Files with new filenames will be generated if needed, and old outdated files will be removed at the same time. All files with a matching name e.g. </tt>output_filename</tt> 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.
`COMPRESS_VERSION` Example:
{{{
</tt>COMPRESS_VERSION</tt> Example:
<code>
COMPRESS = True
COMPRESS_VERSION = True
COMPRESS_CSS = {
...
...
@@ -47,21 +54,23 @@ COMPRESS_CSS = {
'output_filename': 'c/screen.r?.css',
},
}
}}}
</code>
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 <tt>/media/c/screen.r1213947531.css</tt>, which will be re-generated and updated when you change your source files.
* `COMPRESS_CSS_FILTERS`: A tuple of filters to be applied to CSS files. Defaults to `('compress.filters.csstidy.CSSTidyFilter', )`. Please note that in order to use CSSTidy, you need to install CSSTidy (see [Installation] for more details).
* `COMPRESS_JS_FILTERS`: A tuple of filters to be applied to JavaScript files. Defaults to `('compress.filters.jsmin.JSMinFilter',)`
* </tt>COMPRESS_CSS_FILTERS</tt>: A tuple of filters to be applied to CSS files. Defaults to </tt>('compress.filters.csstidy.CSSTidyFilter', )</tt>. Please note that in order to use CSSTidy, you need to install CSSTidy (see [Installation] for more details).
* </tt>COMPRESS_JS_FILTERS</tt>: A tuple of filters to be applied to JavaScript files. Defaults to </tt>('compress.filters.jsmin.JSMinFilter',)</tt>
`COMPRESS_*_FILTERS` can be set to an empty tuple or None to not use any filters. The files will however still be concatenated to one file.
</tt>COMPRESS_*_FILTERS</tt> can be set to an empty tuple or None to not use any filters. The files will however still be concatenated to one file.
h4. CSSTidy settings
== CSSTidy settings ==
If you choose to use CSSTidy (which is enabled by default), you can also use the following settings:
* `CSSTIDY_BINARY`: name or path of the CSSTidy binary to be used for processing JavaScript-files with the CSSTidy filter. Defaults to `'csstidy'`.
* `CSSTIDY_ARGUMENTS`: specifies arguments to be passed to CSSTidy. Defaults to `'--template=highest'`. See CSSTidy man-page or website for more details.
* </tt>CSSTIDY_BINARY</tt>: name or path of the CSSTidy binary to be used for processing JavaScript-files with the CSSTidy filter. Defaults to </tt>'csstidy'</tt>.
* </tt>CSSTIDY_ARGUMENTS</tt>: specifies arguments to be passed to CSSTidy. Defaults to </tt>'--template=highest'</tt>. See CSSTidy man-page or website for more details.
h4. YUI Compressor settings
== YUI Compressor settings ==
* `COMPRESS_YUI_BINARY`: command line to execute for the YUI program. Defaults to `'java -jar yuicompressor.jar'`. You will most likely change this to the location of yuicompressor on your system.
* `COMPRESS_YUI_CSS_ARGUMENTS`: Additional arguments to use when compressing CSS. Defaults to `''`.
* `COMPRESS_YUI_JS_ARGUMENTS`: Additional arguments to use when compressing JavaScript. Defaults to `''`.
\ No newline at end of file
* </tt>COMPRESS_YUI_BINARY</tt>: command line to execute for the YUI program. Defaults to </tt>'java -jar yuicompressor.jar'</tt>. You will most likely change this to the location of yuicompressor on your system.
* </tt>COMPRESS_YUI_CSS_ARGUMENTS</tt>: Additional arguments to use when compressing CSS. Defaults to </tt>''</tt>.
* </tt>COMPRESS_YUI_JS_ARGUMENTS</tt>: Additional arguments to use when compressing JavaScript. Defaults to </tt>''</tt>.
#summary Describes how to customize and add your own functionality to django-compress
h1. Customization
_Describes how to customize and add your own functionality to django-compress_
django-compress can be customized an a couple of ways.
If you need to change the output of the HTML-tags generated from the templatetags, this can be done by overriding the templates `compress/css.html` and `compress/js.html`.
If you need to change the output of the HTML-tags generated from the templatetags, this can be done by overriding the templates <tt>compress/css.html</tt> and <tt>compress/js.html</tt>.
You can also write your own filter-class, if you for example want to implement other types of compressors. All you need to do is to define a filter_css and/or a filter_js functions in a class that inherits from `compress.filter_base.FilterBase`, and specify it in the tuple of filters (`COMPRESS_CSS_FILTERS`/`COMPRESS_JS_FILTERS`) (see [Configuration] for more information) in the settings.
You can also write your own filter-class, if you for example want to implement other types of compressors. All you need to do is to define a filter_css and/or a filter_js functions in a class that inherits from <tt>compress.filter_base.FilterBase</tt>, and specify it in the tuple of filters (<tt>COMPRESS_CSS_FILTERS</tt>/<tt>COMPRESS_JS_FILTERS</tt>) (see [Configuration] for more information) in the settings.
For now, see the files under [http://django-compress.googlecode.com/svn/trunk/filters/ filters/] for more details. CSSTidyFilter uses and external program, and JSMinCompressor just calls a Python-function, so it will probably be able to point you in the right direction when writing custom filters.
#summary Details about the "Far Future Expires" technique, and how to implement it with help from django-compress
h1. Far Future Expires
_Details about the "Far Future Expires" technique, and how to implement it with help from django-compress_
h3. General details and considerations about the "Far Future Expires" technique
= General details and considerations about the "Far Future Expires" technique =
(you can skip this if you already know what it is)
If you really want to make sure that your CSS and JavaScript files get cached by the browser (and possibly by proxies), you should use "Far Future Expires". This means that you send the Expires HTTP-header with a date that is far in the future, resulting in the file being cached at the client (almost) forever
...
...
@@ -11,38 +14,44 @@ Most modern browser implement "Heuristic expiration", so it will actually not be
This technique obviously has a drawback, when you want to change your files, you need to change their names, since their URLs will be cached... that's right: forever! The solution to that is pretty obvious too: change the URLs.
= django-compress with COMPRESS_VERSION =
h3. django-compress with COMPRESS_VERSION
If you specify <tt>COMPRESS_VERSION</tt> in your configuration, you can add a placeholder to the filenames to output the version number of the different files. See [Configuration]) for more information. The filename itself will be changed when any of the source files are updated.
If you specify `COMPRESS_VERSION` in your configuration, you can add a placeholder to the filenames to output the version number of the different files. See [Configuration]) for more information. The filename itself will be changed when any of the source files are updated.
h3. Configuration of web server (that serves MEDIA_URL)
h4. Apache
= Configuration of web server (that serves MEDIA_URL) =
== Apache ==
Expires-control in Apache is handled by mod_expires:
See documentation for more information:
* [http://httpd.apache.org/docs/2.2/mod/mod_expires.html mod_expires in Apache documentation]
* [http://httpd.apache.org/docs/2.2/mod/mod_expires.html mod_expires in Apache documentation]
=== Example ===
{{{
h4. Example
<code>
<Directory /your/media/root/css>
ExpiresActive on
ExpiresDefault "access plus 10 years"
</Directory>
}}}
</code>
Apache also allows the specify files by their mime-type:
{{{
<code>
ExpiresActive On
ExpiresByType text/css "access plus 10 years"
ExpiresByType application/x-javascript "access plus 10 years"
}}}
== lighttpd ==
</code>
h4. lighttpd
lighttpd handles Expires similar to Apache, with a module called mod_expire.
* [http://trac.lighttpd.net/trac/wiki/Docs%3AModExpire mod_expire in lighttpd documentation]
=== Example ===
* [http://trac.lighttpd.net/trac/wiki/Docs%3AModExpire mod_expire in lighttpd documentation]
h4. Example
Set far future headers on all files under /media/css/ and /media/js/.
nginx's `ngx_http_headers_module` provides the `expires` option, which control the `Expires` and `Cache-Control` HTTP headers.
* [http://wiki.codemongers.com/NginxHttpHeadersModule ngx_http_headers_module in nginx documentation]
=== Example ===
</code>
h4. nginx
nginx's <tt>ngx_http_headers_module</tt> provides the <tt>expires</tt> option, which control the <tt>Expires</tt> and <tt>Cache-Control</tt> HTTP headers.
* [http://wiki.codemongers.com/NginxHttpHeadersModule ngx_http_headers_module in nginx documentation]
h4. Example
This will set expiration to the maximum expiration:
This is a application that will provide an easy and automated way to output compressed/minified CSS and JavaScript. It adheres to the DRY principle, you set up your CSS-files and JavaScript-files in your project settings, and you are done. There is no need to enter the names in your template again (a couple of template tags takes care of that).
* Group/concatenate your CSS/JavaScript source files to single files, and run the code through specified filters
* Provides sane defaults for CSS (CSSTidy required) and JavaScript minification.
* A filter for YUI Compressor is included.
* It’s easy and straightforward to write custom compressors/filters to generate the output. Filters for jsmin and CSSTidy is included by default.
* A last-modifcation/version part can automatically be appended to the filename of the outputted files to make use of “far future Expires HTTP header), and provide an automated way of updating the content without delays.
* You setup and group your CSS and JavaScript-files in the settings, and set up whetter or not you want your files to be compressed.
* Templatetags to output CSS (<link...>) or JavaScript (<script...>) tags with the compressed files if COMPRESS = True, or otherwise the source files.
* The compressed files will be updated (if neeeded) when you are accessing them from the templatetags. This only applies when COMPRESS_AUTO is enabled. You can manually update them with “./manage.py synccompress”.
\ No newline at end of file
* Group/concatenate your CSS/JavaScript source files to single files, and run the code through specified filters
* Provides sane defaults for CSS (CSSTidy required) and JavaScript minification.
* A filter for YUI Compressor is included.
* It’s easy and straightforward to write custom compressors/filters to generate the output. Filters for jsmin and CSSTidy is included by default.
* A last-modifcation/version part can automatically be appended to the filename of the outputted files to make use of “far future Expires HTTP header), and provide an automated way of updating the content without delays.
* You setup and group your CSS and JavaScript-files in the settings, and set up whetter or not you want your files to be compressed.
* Templatetags to output CSS (<link...>) or JavaScript (<script...>) tags with the compressed files if COMPRESS = True, or otherwise the source files.
* The compressed files will be updated (if neeeded) when you are accessing them from the templatetags. This only applies when COMPRESS_AUTO is enabled. You can manually update them with “./manage.py synccompress”.
#summary Installation instructions for django-compress
h1. Installation
Installation is pretty straight-forward and follows the same installation procedure as many other Django applications. django-compress does not create any models, so you do not need to configure a database.
== Recommendations ==
h3. Recommendations
By default django-compress uses CSSTidy to compress CSS. CSSTidy is an excellent stand-alone application for dealing with CSS-files. CSSTidy can be downloaded from: http://csstidy.sourceforge.net/. If you do not install CSSTidy, make sure to disable the filter in your settings (by setting COMPRESS_CSS_FILTERS = None).
== Install instructions ==
# Get the code from svn: `svn co http://django-compress.googlecode.com/svn/trunk/ django-compress`
#
# Use the `setup.py` script to install: `python setup.py install`
# OR manually put the `compress`-directory somewhere on your PYTHONPATH
# Add `'compress'` to your INSTALLED_APPS
h3. Install instructions
# Get the code from svn: svn co http://django-compress.googlecode.com/svn/trunk/ django-compress
** Use the setup.py script to install: python setup.py install
** OR manually put the compress-directory somewhere on your PYTHONPATH
# Add 'compress' to your INSTALLED_APPS
h3. Using git?
== Using git? ==
The main source repository is now available at github: http://github.com/pelme/django-compress/tree/master
The Subversion repository at Google Code will still be updated, though.
If you want to grab django-compress via git, use:
`git://github.com/pelme/django-compress.git`
\ No newline at end of file
If you want to grab django-compress via git, use: git://github.com/pelme/django-compress.git
#summary Short introduction to performance tweaks and what django-compress does
h1. Introduction
_Short introduction to performance tweaks and what django-compress does_
JavaScript and CSS minification/compression can decrease load times of sites a lot.
It is important to reduce the number of requests that are made. Fewer files means better performance. However, when you develop CSS, and particularly if you are building a big site, it can be nice to separate different parts of the site’s CSS into different files. You also want to keep the CSS and JavaScript in different files while you develop, to make debugging easier.
...
...
@@ -8,11 +11,11 @@ You also want to make sure that as much of the static content is cached as much
These techniques has been described more in depth at Yahoo:
django-compress tries to address those issues with as little manual intervention as possible, whilst still being configurable enough to not get in your way. Read more about the [Features].
There are numerous of other techniques that could be used to improve performance, Yahoo has an excellent page that lists the most common:
#summary Describes how to use django-compress when it is installed and configured
h1. Usage
= Automated generation =
If `COMPRESS` and `COMPRESS_AUTO` is enabled (`True`), the source files will be automatically updated, and re-generated IF NEEDED when invoked from the templatetags. The last modified time of the files will be compared, and if any of the source-files is newer than the output-file, the file will be re-generated.
_Describes how to use django-compress when it is installed and configured_
h3. Automated generation
If <tt>COMPRESS</tt> and <tt>COMPRESS_AUTO</tt> is enabled (<tt>True</tt>), the source files will be automatically updated, and re-generated IF NEEDED when invoked from the templatetags. The last modified time of the files will be compared, and if any of the source-files is newer than the output-file, the file will be re-generated.
h3. Management command
= Management command =
You can update and force updates of the compressed file(s) with the management command “synccompress”. This makes it possible to keep the files updated manually.
The command is
{{{
<code>
./manage.py synccompress
}}}
(assuming you are in you project-folder that contains `manage.py`). To force all files to be re-generated, use the argument `--force` (e.g. `./manage.py synccompress --force`)
</code>
(assuming you are in you project-folder that contains <tt>manage.py</tt>). To force all files to be re-generated, use the argument <tt>--force</tt> (e.g. <tt>./manage.py synccompress --force</tt>)
= Templatetags =
django-compress includes two template tags: `compressed_css` and `compressed_js`, in a template library called `compressed`
h3. Templatetags
django-compress includes two template tags: <tt>compressed_css</tt> and <tt>compressed_js</tt>, in a template library called <tt>compressed</tt>
They are used to output the <link> and <script>-tags for the specified CSS/JavaScript-groups (as specified in the settings). The first argument must be the name of the CSS/JavaScript group.
The templatetags will either output the source filenames or the compressed filenames, depending on the `COMPRESS` setting, if you do not specify the `COMPRESS` setting, the source files will be used in DEBUG-mode, and compressed files in non-DEBUG-mode.
== Example ==
The templatetags will either output the source filenames or the compressed filenames, depending on the <tt>COMPRESS</tt> setting, if you do not specify the <tt>COMPRESS</tt> setting, the source files will be used in DEBUG-mode, and compressed files in non-DEBUG-mode.
h4. Example
If you have specified the CSS-groups “my_screen_css” and “my_print_css” and a JavaScript-group with the name “my_scripts”, you would use the following code to output them all:
{{{
<code>
{% load compressed %}
{% compressed_css 'my_screen_css' %}
{% compressed_css 'my_print_css' %}
{% compressed_js 'my_scripts' %}
}}}
</code>
h3. Far future Expires
= Far future Expires =
Far future Expires can be used with the `bump_filename`-option, see the [FarFutureExpires] page for more information.
\ No newline at end of file
Far future Expires can be used with the bump_filename-option, see the FarFutureExpires page for more information.
