Helpers

Context processors

The static context processor

context_processors.static()

This context processor adds the STATIC_URL into each template context as the variable {{ STATIC_URL }}. To use it, make sure that 'staticfiles.context_processors.static' appears somewhere in your TEMPLATE_CONTEXT_PROCESSORS setting.

Remember, only templates rendered with a RequestContext will have acces to the data provided by this (and any) context processor.

Template tags

static

templatetags.staticfiles.static()

New in version 1.1.

Uses the configued STATICFILES_STORAGE storage to create the full URL for the given relative path, e.g.:

{% load staticfiles %}
<img src="{% static "css/base.css" %}" />

The previous example is equal to calling the url method of an instance of STATICFILES_STORAGE with "css/base.css". This is especially useful when using a non-local storage backend to deploy files to a CDN.

get_static_prefix

templatetags.static.get_static_prefix()

If you’re not using RequestContext, or if you need more control over exactly where and how STATIC_URL is injected into the template, you can use the get_static_prefix template tag instead:

{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" />

There’s also a second form you can use to avoid extra processing if you need the value multiple times:

{% load static %}
{% get_static_prefix as STATIC_PREFIX %}

<img src="{{ STATIC_PREFIX }}images/hi.jpg" />
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" />

get_media_prefix

templatetags.static.get_media_prefix()

Similar to get_static_prefix() but uses the MEDIA_URL setting instead.

Storages

StaticFilesStorage

class storage.StaticFilesStorage

A subclass of the FileSystemStorage storage backend that uses the STATIC_ROOT setting as the base file system location and the STATIC_URL setting respectively as the base URL.

post_process(paths, **options)

New in version 1.1.

This method is called by the collectstatic management command after each run and gets passed the paths of found files, as well as the command line options.

The CachedStaticFilesStorage uses this behind the scenes to replace the paths with their hashed counterparts and update the cache appropriately.

CachedStaticFilesStorage

class storage.CachedStaticFilesStorage

New in version 1.1.

A subclass of the StaticFilesStorage storage backend which caches the files it saves by appending the MD5 hash of the file’s content to the filename. For example, the file css/styles.css would also be saved as css/styles.55e7cbb9ba48.css.

The purpose of this storage is to keep serving the old files in case some pages still refer to those files, e.g. because they are cached by you or a 3rd party proxy server. Additionally, it’s very helpful if you want to apply far future Expires headers to the deployed files to speed up the load time for subsequent page visits.

The storage backend automatically replaces the paths found in the saved files matching other saved files with the path of the cached copy (using the post_process() method). The regular expressions used to find those paths (storage.CachedStaticFilesStorage.cached_patterns) by default cover the @import rule and url() statement of Cascading Style Sheets. For example, the 'css/styles.css' file with the content

@import url("../admin/css/base.css");

would be replaced by calling the url() method of the CachedStaticFilesStorage storage backend, ultimatively saving a 'css/styles.55e7cbb9ba48.css' file with the following content:

@import url("/static/admin/css/base.27e20196a850.css");

To enable the CachedStaticFilesStorage you have to make sure the following requirements are met:

  • the STATICFILES_STORAGE setting is set to 'staticfiles.storage.CachedStaticFilesStorage'
  • the DEBUG setting is set to False
  • you use the staticfiles static() template tag to refer to your static files in your templates
  • you’ve collected all your static files by using the collectstatic management command

Since creating the MD5 hash can be a performance burden to your website during runtime, staticfiles will automatically try to cache the hashed name for each file path using Django’s caching framework. If you want to override certain options of the cache backend the storage uses, simply specify a custom entry in the CACHES setting named 'staticfiles'. It falls back to using the 'default' cache backend.

Static file development view

staticfiles.views.serve(request, path)

This view function serves static files in development.

Warning

This view will only work if DEBUG is True.

That’s because this view is grossly inefficient and probably insecure. This is only intended for local development, and should never be used in production.

This view is automatically enabled by runserver (with a DEBUG setting set to True). To use the view with a different local development server, add the following snippet to the end of your primary URL configuration:

from django.conf import settings

if settings.DEBUG:
    urlpatterns += patterns('staticfiles.views',
        url(r'^static/(?P<path>.*)$', 'serve'),
    )

Note, the begin of the pattern (r'^static/') should be your STATIC_URL setting.

URL patterns helper

staticfiles.urls.staticfiles_urlpatterns()

Warning

This helper function will only work if DEBUG is True and your STATIC_URL setting is neither empty nor a full URL such as http://static.example.com/.

Since configuring the URL patterns is a bit finicky, there’s also a helper function that’ll do this for you.

This will return the proper URL pattern for serving static files to your already defined pattern list. Use it like this:

from staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()