Django facets is an assets manager providing a cache manager for static files, CSS, Javascript, images compression and a collection (concatenation) system for CSS and JavaScript.
This new version uses Django static storage system.
- Download the package and type
python setup.py install
- Add
django.contrib.staticfiles
andfacets
to yourINSTALLED_APPS
- Set
STATICFILES_STORAGE
setting tofacets.storages.FacetsFilesStorage
- Add, in first position
facets.finders.FacetsFinder
toSTATICFILES_FINDERS
setting
Django facets needs some configuration settings.
This setting enables cache. Its default value is the negation of DEBUG
setting. You can set it manualy if you want to test your cache in debug mode.
Django Facets keeps track of cached files using Django cache system. It tries to use the cache named "facets" and falls back to default. Here a configuration example:
CACHES = CACHES = {
'default': {
# Whatever you want
},
'facets': {
'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
'LOCATION': '/path/to/directory'
}
}
A list of handlers. The default value is:
(
'facets.processors.css.CssUrlsProcessor',
)
These handlers are called during static files collect and/or while compiling some files. Order does not matter.
See handlers section.
All static files should be handled as with Django staticfiles.
Collections are files you want to concatenate while in production. To create a collection, you should use the mediacollection
template tag. Here's an example:
{% load static from staticfiles %}
{% load facets %}
{% mediacollection "css/main.css" %}
<link rel="stylesheet" href="{% static "css/reset.css" %}" />
<link rel="stylesheet" href="{% static "css/screen.css" %}" />
{% endmediacollection %}
The argument of the tag is the collection's final name.
Collections follow some rules:
- Only for
link
andscript
HTML tags. - You can't mix
link
andscript
tags together. - With
link
tags, the following attributes must have the same values on each tag:rel
,type
,media
- With
script
tags, the following attributes must have the same values on each tag:type
Before using the cache, you should run ./manage.py collectstatic
. This command generates cached files.
You could run this command during project deployment. Please note that you MUST restart your project server after running collectstatic.
Handlers are classes that take responsibility to transform an input file. There are two types of handlers: compilers and processors.
Compilers create final files for some preprocessors languages (Less, Sass, CoffeeScript, etc.). A compiler will be called during collectstatic and while serving static files if setting FACETS_ENABLED
is set to False
(usually during development).
Please note that there can be only one compiler by file extension.
- Extensions
less
- Options
new_name:{base}.css
program:/usr/bin/env lessc
command:{program} - {outfile}
This compiler compiles Less files using Less preprocessor.
- Extensions
scss
,sass
- Options
new_name:{base}.css
program:/usr/bin/env sassc
command:{program} -
This compiler compiles Sass files using SassC preprocessor.
- Extensions
scss
,sass
This compiler compiles Sass files using libsass-python preprocessor.
- Extensions
coffee
- Options
new_name:{base}.js
program:/usr/bin/env coffee
command:{program} -c --print {infile}
This compiler compiles CoffeeScript files using CoffeeScript command.
- Extensions
ls
- Options
new_name:{base}.js
program:/usr/bin/env lsc
command:{program} -c --print {infile}
This compiler compiles LiveScript files using LiveScript command.
- Extensions
dart
- Options
new_name:{base}.js
program:/usr/bin/env dart2js
command:{program} -o {outfile} {infile}
This compiler compiles Dart files using Dart dart2js.
Processors are called during collectstatic. Their job is usually to optimize files.
- Scope
*.css
- Options
priority: -1000 (please don't change it)
This processor transforms every URL found in CSS files to point to cached files version. For example, this rule:
h1 {
background: url(../img/title.png);
}
would become:
h1 {
background: url("/static/img/title-e221e1b36656.png");
}
Note: It is recommended to always have this processor set.
- Scope
*.css
This processor minifies CSS files using cssmin.
- Scope
*.js
This processor minifies JavaScript files using jsmin.
- Scope
*.js
- Options
program:/usr/bin/env uglifyjs
command:{program} {infile} --ascii -m -c -o {outfile}
This processor minifies JavaScript files using UglifyJs 2.
- Scope
*.js
- Options
program:/usr/bin/env java -jar /path/to/compiler.jar
(you'll have to change that)
command:{program} {infile}
This processor minifies JavaScript files using Google Closure Compiler.
- Scope
*.js
- Options
program:/usr/bin/env java -jar /path/to/yuicompressor-xxx.jar
(you'll have to change that)
command:{program} {infile}
This processor minifies JavaScript files using Yahoo UI Compressor.
- Scope
*.css
- Options
program:/usr/bin/env java -jar /path/to/yuicompressor-xxx.jar
(you'll have to change that)
command:{program} {infile}
This processor minifies CSS files using Yahoo UI Compressor.
- Scope
*.png
- Options
program:/usr/bin/env optipng
command:{program} -o7 -nc {infile}
This processor optimizes PNG files using OptiPNG.
- Scope
*.png
- Options
program:/usr/bin/env advpng
command:{program} -z -4 {infile}
This processor optimizes PNG files using AdvanceCOMP advpng.
- Scope
*.jpg, *.jpeg
- Options
program:/usr/bin/env jpegtran
command:{program} -copy none -optimize {infile}
This processor optimizes JPEG files using jpegtran.
- Scope
*.jpg, *.jpeg
- Options
program:/usr/bin/env jpegoptim
command:{program} -q --strip-all {infile}
This processor optimizes JPEG files using jpegoptim.
- Scope
*.gif
- Options
program:/usr/bin/env gifsicle
command:{program} --batch -O3 {infile}
This processor optimizes GIF files using Gifsicle.
- Scope
*.htm, *.html, *js, *.css, *.txt, *.eot, *.ttf, *.woff, *.svg
- Options
priority: 1000 (please don't change it)
compresslevel: A compression level (0-9). Default to 5.
This processor is a bit special. Instead of updating existing cached file, it creates a gziped copy. It could be very useful if you configured Nginx with Gzip Static Module.
Django facets is released under the BSD license. See the LICENSE file for the complete license.