mirror of
https://github.com/samuelclay/NewsBlur.git
synced 2025-08-31 21:41:33 +00:00
156 lines
No EOL
8.9 KiB
Text
156 lines
No EOL
8.9 KiB
Text
h1. Configuration
|
|
|
|
Configuration and list of available settings for django-compress
|
|
|
|
*Don't forget 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. Prefix - An Alternative to MEDIA_URL
|
|
|
|
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:
|
|
|
|
<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',
|
|
'prefix': 'http://cdn.example.com/'
|
|
},
|
|
},
|
|
|
|
# other CSS groups goes here
|
|
}
|
|
</code></pre>
|
|
|
|
In this example, the template tags will render _http://cdn.example.com/css/one_compressed.css_ in the link tag. You will need to manually put there after you build as part of your deployment process.
|
|
|
|
h4. External urls
|
|
|
|
While django-compress does a great job of minimizing the amount of http requests on your site (hence increasing performence) there are sometimes cases
|
|
when you want to include external files aswell. Lets take an example:
|
|
|
|
<pre><code>
|
|
COMPRESS_JS = {
|
|
'jquery': {
|
|
'external_urls': (
|
|
'http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js',
|
|
'http://ajax.googleapis.com/ajax/libs/jqueryui/1.5.2/jquery-ui.min.js'
|
|
),
|
|
},
|
|
'all': {
|
|
'source_filenames': ('js/blog.js', 'js/comments.js'),
|
|
'output_filename': 'js/all.js',
|
|
},
|
|
}
|
|
</code></pre>
|
|
In template:
|
|
<pre><code>
|
|
{% load compressed %}
|
|
{% compressed_js 'jquery' %}
|
|
{% compressed_js 'all' %}
|
|
</code></pre>
|
|
Output in when <tt>settings.COMPRESS = False</tt>
|
|
<pre><code>
|
|
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js" charset="utf-8"></script>
|
|
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.5.2/jquery-ui.min.js" charset="utf-8"></script>
|
|
<script type="text/javascript" src="/media/js/blog.js" charset="utf-8"></script><script type="text/javascript" src="/media/js/comments.js" charset="utf-8"></script>
|
|
</code></pre>
|
|
|
|
Output in when <tt>settings.COMPRESS = True</tt>
|
|
<pre><code>
|
|
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js" charset="utf-8"></script>
|
|
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.5.2/jquery-ui.min.js" charset="utf-8"></script>
|
|
<script type="text/javascript" src="/media/js/all.js" charset="utf-8"></script>
|
|
</code></pre>
|
|
|
|
Now why is this good you ask? The more script sources the more impact on performence according to http://developer.yahoo.com/performance/rules.html#num_http
|
|
which is true but if you are low bandwidth or superbig you may want to offload
|
|
some horsepower to google which leads us as hinted in the example above to the next topic.
|
|
|
|
Note: external urls is currently only available for javascript. There's
|
|
currently no reason to have external css files (Yes there are css frameworks aswell on the net but they are often very small or generated to fit your needs)
|
|
|
|
h4. Google AJAX Libraries API
|
|
|
|
So the reason for adding external urls support to django-compress is google ajax libraries api support (example above) but you may want to use it however you want.
|
|
|
|
The advantages for offloading huge javascript libraries to google cdn is of course that your site will need a lot less bandwidth, even if you use far futures expires headers. But the superior reason is of course that the more sites that uses it, the bigger the chance is that your favorite js framework is already cached in your visitors browser.
|
|
|
|
Google also uses far future expires headers so don't worry about that. Don't worry about latency outside the US either. Here in sweden I measuerd a latencey of 39ms.
|
|
|
|
To sum somethings up, it's up to you and your situation to decide if merging all js files or offloading js libraries to google gives your site the best performence. Both ways are great to achive great performence.
|
|
|
|
For a complete list of javascript libraries supported go to http://code.google.com/apis/ajaxlibs/
|
|
|
|
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>. |