Merge branch 'master' of git://github.com/andriijas/django-compress

git-svn-id: https://django-compress.googlecode.com/svn/trunk@82 98d35234-f74b-0410-9e22-51d878bdf110

docs/BackwardsIncompatibleChanges.textile

+h1. Backwards Incompatible Changes
+
+_A list of backwards incompatible changes_
+
+h3. Revision 53
+
+http://code.google.com/p/django-compress/source/detail?r=53
+
+Changed the default media type for CSS to "all" instead of "media,projection". You can still specify media type with `extra_context`.
+h3. Revision 56
+
+http://code.google.com/p/django-compress/source/detail?r=56
+
+*bump_filename completely changed*
+
+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.
+
+* The `bump_filename` option was removed from the group settings. There is no need specifying it for ALL groups, if you actually use it, you most likely want to use it on all your compressed files.
+* The bump_filename options is replaced by the setting COMPRESS_VERSION, and is completely ignored.
+* The querystring is no longer used to determine a files version, since it was use
+* If COMPRESS_VERSION is used, you specify the version part of the `output_filename` file with '?'. This placeholder can be changed with COMPRESS_VERSION_PLACEHOLDER. 
+
+E.g.:
+<pre>
+<pre><code>
+'screen': {
+    'source_filenames': ('css/screen/style.css', 'css/screen/paginator.css', 'css/screen/agenda.css', 'css/screen/weather.css', 'css/screen/gallery.css', ),
+    'output_filename': 'c/screen.r?.css',
+},
+</code></pre>
+</pre>
+
+* COMPRESS_VERSION requires COMPRESS_AUTO to be enabled. COMPRESS_AUTO is enabled by default, but if you explicitly set it to `False` an ImproperlyConfiguredError exception will be thrown. 
+
+COMPRESS_AUTO changes
+
+* The CSS/Javascript files are not checked during Django's initialization anymore. It was not really useful and did not make sense. The automatic part is now handled by the templatetags (i.e. what used to be COMPRESS_TEMPLATE_AUTO).
+* COMPRESS_AUTO is replaced by COMPRESS_AUTO_TEMPLATE, and the old behavior of COMPRESS_AUTO is removed. This might be really confusing, the Configuration should make it clear. 
\ No newline at end of file

docs/Configuration.textile

+h1. Configuration
+
+Configuration and list of available settings for django-compress
+
+*Don't forgett to read BackwardsIncompatibleChanges*
+
+h3. Specifying files
+
+You specify groups of files to be compressed in your settings. The basic syntax for specifying CSS/JavaScript groups files is:
+
+<pre><code>
+COMPRESS_CSS = {
+    'group_one': {
+        'source_filenames': ('css/style.css', 'css/foo.css', 'css/bar.css'),
+        'output_filename': 'css/one_compressed.css',
+        'extra_context': {
+            'media': 'screen,projection',
+        },
+    },
+    
+    # other CSS groups goes here
+}
+
+COMPRESS_JS = {
+    'all': {
+        'source_filenames': ('js/jquery-1.2.3.js', 'js/jquery-preload.js', 'js/jquery.pngFix.js',
+        'js/my_script.js', 'js/my_other_script.js'),
+        'output_filename': 'js/all_compressed.js',
+    }
+}
+</code></pre>
+
+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.
+
+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.
+
+</tt>COMPRESS_VERSION</tt> Example:
+<pre><code>
+COMPRESS = True
+COMPRESS_VERSION = True
+COMPRESS_CSS = {
+    'screen': {
+        'source_filenames': ('css/screen/style.css', 'css/screen/paginator.css', 'css/screen/agenda.css', 'css/screen/weather.css', 'css/screen/gallery.css', ),
+        'output_filename': 'c/screen.r?.css',
+    },
+}
+</code></pre>
+
+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.
+
+* </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>
+
+</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
+
+If you choose to use CSSTidy (which is enabled by default), you can also use the following settings:
+* </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
+
+* </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>.
\ No newline at end of file

docs/Customization.textile

+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 <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 <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.
\ No newline at end of file

docs/FarFutureExpires.textile

+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
+
+(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
+
+If you do not specify an Expires header, the files will be requested again, and the server will respond "304 Not Modified" - which means that the file that the client got in its cache is still up-to-date. *However, a HTTP request will still be made anyway.* The actual data does not get sent, but there will still be unnecessary HTTP requests, which can be avoided.
+
+Most modern browser implement "Heuristic expiration", so it will actually not be "304 Not Modified" for your static files on every request, however, the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html HTTP specification does not specify] (see section 13.2.2) how "Heuristic expiration" should be handled by the browsers. Therefore it is recommended to explicitly set the Expires header, to make sure all browsers cache the files in the preferred way.
+
+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.
+
+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.
+
+h3. Configuration of web server (that serves MEDIA_URL)
+
+h4. 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]
+
+h4. Example
+<pre><code>
+<Directory /your/media/root/css>
+    ExpiresActive on
+    ExpiresDefault "access plus 10 years"
+</Directory>
+</code></pre>
+
+Apache also allows the specify files by their mime-type:
+<pre><code>
+ExpiresActive On
+ExpiresByType text/css "access plus 10 years"
+ExpiresByType application/x-javascript "access plus 10 years"
+</code></pre>
+
+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]
+
+h4. Example
+
+Set far future headers on all files under /media/css/ and /media/js/.
+
+<pre><code>
+$HTTP["url"] =~ "^/media/css/" {
+     expire.url = ( "" => "access 10 years" )
+}
+
+$HTTP["url"] =~ "^/media/js/" {
+     expire.url = ( "" => "access 10 years" )
+}
+</code></pre>
+
+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:
+<pre><code>
+location /media/js {
+    expires max;
+}
+
+location /media/css {
+    expires max;
+}
+</code></pre>
\ No newline at end of file

docs/Features.textile

+h1. django-compress features
+
+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

docs/Installation.textile

+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.
+
+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).
+
+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?
+
+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

docs/Introduction.textile

+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.
+
+It is also nice to comment CSS and JavaScript, but you do not want the overhead of sending the comments and whitespaces to the clients.
+
+You also want to make sure that as much of the static content is cached as much as possible at the client. The ideal is to even avoid “304 Not Modified” which are returned when a client requested something that has already been cached, and does not need to be updated. This can be accomplished by setting the HTTP Expire header to a date far in the future. That will force the browser not to ask for updates for that URL. However, when you need to update your files, you will need to give them a new URL, to push the updated files to the clients.
+
+These techniques has been described more in depth at Yahoo:
+
+* http://developer.yahoo.com/performance/rules.html#num_http
+* http://developer.yahoo.com/performance/rules.html#minify
+* http://developer.yahoo.com/performance/rules.html#expires
+
+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:
+* http://developer.yahoo.com/performance/rules.html
\ No newline at end of file

docs/Usage.textile

+h1. Usage
+
+_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
+
+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
+<pre><code>
+./manage.py synccompress
+</code></pre>
+
+(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>)
+
+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 <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:
+
+<pre><code>
+{% load compressed %}
+{% compressed_css 'my_screen_css' %}
+{% compressed_css 'my_print_css' %}
+{% compressed_js 'my_scripts' %}
+</code></pre>
+
+h3. 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