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¶
New in version 1.1.
Uses the configured 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¶
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" />
Storages¶
StaticFilesStorage¶
-
class
storage.
StaticFilesStorage
¶ A subclass of the
FileSystemStorage
storage backend that uses theSTATIC_ROOT
setting as the base file system location and theSTATIC_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 filecss/styles.css
would also be saved ascss/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 theCachedStaticFilesStorage
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 toFalse
- 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 theCACHES
setting named'staticfiles'
. It falls back to using the'default'
cache backend.- the
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()