Template Usage
To use these cache-busting template tags, you’ll need to load the template tag module at the top of each template with {% load cachebuster %}. Alternatively, as these tags will most likely be used in most of a project’s templates, you can tell Django to auto-load them without the requisite {% load cachebuster %} by adding the following to your settings.py:
from django.template.loader import add_to_builtins
add_to_builtins('cachebuster.templatetags.cachebuster')
{% static filename %} attempts to use the CACHEBUSTER_UNIQUE_STRING (see Configuration below) setting to get a cached value to append to your static URLs (ie. STATIC_URL). If CACHEBUSTER_UNIQUE_STRING is not set, it falls back to the last date modified of the file. If CACHEBUSTER_UNIQUE_STRING is used, you can force last-date-modified behaviour by adding True into the tag statement like so: {% static filename True %}. For example
<link rel="stylesheet" href="{% static css/reset.css %}" type="text/css">
<link rel="stylesheet" href="{% static css/fonts.css True %}" type="text/css">
This would yield something along the lines of:
<link rel="stylesheet" href="/static/css/reset.css?927f6b650afce4111514" type="text/css">
<link rel="stylesheet" href="/static/css/fonts.css?015509150311" type="text/css">
{% media filename %} is similar but has slightly different behaviour, as the file content has a different origin (user uploaded content like avatars, videos, etc.) and cannot depend on any git comment hash. This is why there is no behaviour other than the last modified date method for MEDIA_URL files.
<img src='{% media uploads/uid1-avatar.jpg %}' />
would result in something like this:
<img src='/media/uploads/uid1-avatar.jpg?034511190510' />
Configuration
django-cachebuster supports two methods of ‘busting’. Appending a unique string (by default, this is the last modified datetime of the file) as a query string parameter is the easy, default behaviour. For more advanced requirements such as content distribution network (CDN, such as CloudFront) scenarios, there is also the ability to prepend the unique string.
To start using it in it’s simplest form right now, see the Template Usage section. Want more from django-cachebuster? Read on.
CACHEBUSTER_UNIQUE_STRING: optional; defaults to the file’s last modified timestamp.
This is a simple performance optimization that minimizes accessing the file system to get a file’s last modified timestamp. This optimization is only used for static files (not media/user-generated files) as only static files are usually version-controlled.
To set CACHEBUSTER_UNIQUE_STRING, you would mostly likely use a provided ‘detector’ or write your own (please contribute new ones!). For example, if you use Git as your source control, you can use the provided git detector. It simply traverses the Django project’s path looking for the .git folder, and then extracts the current commit hash. This hash is cached and used for subsequent cache-busting. In your settings.py:
from cachebuster.detectors import git
CACHEBUSTER_UNIQUE_STRING = git.unique_string(__file__)
or if you wanted it to be a short busting string:
from cachebuster.detectors import git
CACHEBUSTER_UNIQUE_STRING = git.unique_string(__file__)[:8]
__file__ must be passed in so that django-cachebuster operates in the context of the Django project’s settings.py file. If it wasn’t passed in, django-cachebuster would only have its own context from which to grab the .git directory, not that of the user’s project. (An alternative to this is to use Python’s inspect module - but there are some warnings around using it.)
CACHEBUSTER_PREPEND_STATIC: optional; defaults to False.
CACHEBUSTER_PREPEND_MEDIA: optional; defaults to False.
If CloudFront or another CDN that ignores query string parameters is used, CACHEBUSTER_PREPEND_STATIC will need to be set to True. For static files, this prepends the unique string instead of appending it as a query string parameter. CACHEBUSTER_PREPEND_MEDIA does the same for media files. For example, with CACHEBUSTER_PREPEND_STATIC set to True, the rendered output becomes:
<link rel="stylesheet" href="/static/927f6b650afce4111514/css/reset.css" type="text/css">
With CACHEBUSTER_PREPEND_STATIC set to False:
<link rel="stylesheet" href="/static/css/reset.css?927f6b650afce4111514" type="text/css">
Using this prepending method raises a couple of development environment issues, however. Assuming Django 1.3 or higher is used, ./manage.py runserver will automatically attempt to serve static (not media, however) files on its own without any urls.py changes; this standard method of serving does not work in this scenario. To prevent this default Django behaviour, the development server should be started with the following command:
./manage.py runserver --nostatic
Also when using the prepending method in a development environment, to support serving files from both {% static %} and {{ STATIC_URL }} (as well as {% media %} and ``{{ MEDIA_URL }}), Django’s default serve views need to be replaced with the following in your urls.py:
if settings.DEBUG:
urlpatterns += patterns('',
url(r'^static/(?P<path>.*)$', 'cachebuster.views.static_serve', {'document_root': settings.STATIC_ROOT,}),
url(r'^media/(?P<path>.*)$', 'cachebuster.views.media_serve', {'document_root': settings.MEDIA_ROOT,}),
)
This is because both the prepended and the non-prepended paths need to be tested to support the above-mentioned scenarios.
