From cfc19f84def07fb950ae8789ed0655eae4f66a92 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Wed, 20 Oct 2010 01:33:24 +0000 Subject: Fixed #12323 and #11582 -- Extended the ability to handle static files. Thanks to all for helping with the original app, the patch, documentation and general support. git-svn-id: http://code.djangoproject.com/svn/django/trunk@14293 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/static-files.txt | 483 +++++++++++++++++++++++++++++---------- docs/index.txt | 3 +- docs/ref/contrib/index.txt | 1 + docs/ref/contrib/staticfiles.txt | 283 +++++++++++++++++++++++ docs/ref/settings.txt | 2 +- docs/ref/templates/api.txt | 9 +- 6 files changed, 655 insertions(+), 126 deletions(-) create mode 100644 docs/ref/contrib/staticfiles.txt (limited to 'docs') diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index 209cf38c36..3b5b7a5683 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -1,162 +1,399 @@ -========================= -How to serve static files -========================= +===================== +Managing static files +===================== -.. module:: django.views.static - :synopsis: Serving of static files during development. +.. currentmodule:: django.contrib.staticfiles -Django itself doesn't serve static (media) files, such as images, style sheets, -or video. It leaves that job to whichever Web server you choose. +.. versionadded:: 1.3 -The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and -Cherokee_, are much more fine-tuned at serving static files than a Web -application framework. +Django developers mostly concern themselves with the dynamic parts of web +applications -- the views and templates that render anew for each request. But +web applications have other parts: the static media files (images, CSS, +Javascript, etc.) that are needed to render a complete web page. -With that said, Django does support static files **during development**. You can -use the :func:`django.views.static.serve` view to serve media files. +For small projects, this isn't a big deal, because you can just keep the media +somewhere your web server can find it. However, in bigger projects -- especially +those comprised of multiple apps -- dealing with the multiple sets of static +files provided by each application starts to get tricky. -.. _Apache: http://httpd.apache.org/ -.. _lighttpd: http://www.lighttpd.net/ -.. _Cherokee: http://www.cherokee-project.com/ +That's what ``django.contrib.staticfiles`` is for: it collects media from each +of your applications (and any other places you specify) into a single location +that can easily be served in production. -.. seealso:: +.. note:: - If you just need to serve the admin media from a nonstandard location, see - the :djadminopt:`--adminmedia` parameter to :djadmin:`runserver`. + If you've used the `django-staticfiles`_ third-party app before, then + ``django.contrib.staticfiles`` will look very familiar. That's because + they're essentially the same code: ``django.contrib.staticfiles`` started + its life as `django-staticfiles`_ and was merged into Django 1.3. + + If you're upgrading from ``django-staticfiles``, please see `Upgrading from + django-staticfiles`_, below, for a few minor changes you'll need to make. -The big, fat disclaimer -======================= +.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ -Using this method is **inefficient** and **insecure**. Do not use this in a -production setting. Use this only for development. +Using ``django.contrib.staticfiles`` +==================================== -For information on serving static files in an Apache production environment, -see the :ref:`Django mod_wsgi documentation `. +Here's the basic usage in a nutshell: -How to do it -============ + 1. Put your media somewhere that staticfiles will find it.. -Here's the formal definition of the :func:`~django.views.static.serve` view: + Most of the time this place will be in a ``static`` directory within your + application, but it could also be a specific directory you've put into + your settings file. See the the documentation for the + :setting:`STATICFILES_DIRS` and :setting:`STATICFILES_FINDERS` settings + for details on where you can put media. -.. function:: def serve(request, path, document_root, show_indexes=False) + 2. Add some ``staticfiles``-related settings to your settings file. -To use it, just put this in your :doc:`URLconf `:: + First, you'll need to make sure that ``django.contrib.staticfiles`` is in + your :setting:`INSTALLED_APPS`. - (r'^site_media/(?P.*)$', 'django.views.static.serve', - {'document_root': '/path/to/media'}), + Next, you'll need to edit :setting:`STATICFILES_ROOT` to point to where + you'd like your static media stored. For example:: -...where ``site_media`` is the URL where your media will be rooted, and -``/path/to/media`` is the filesystem root for your media. This will call the -:func:`~django.views.static.serve` view, passing in the path from the URLconf -and the (required) ``document_root`` parameter. + STATICFILES_ROOT = "/home/jacob/projects/mysite.com/static_media" -Given the above URLconf: + You may also want to set the :setting:`STATICFILES_URL` setting at this + time, though the default value (of ``/static/``) is perfect for local + development. - * The file ``/path/to/media/foo.jpg`` will be made available at the URL - ``/site_media/foo.jpg``. + There are a number of other options available that let you control *how* + media is stored, where ``staticfiles`` searches for files, and how files + will be served; see :ref:`the staticfiles settings reference + ` for details. - * The file ``/path/to/media/css/mystyles.css`` will be made available - at the URL ``/site_media/css/mystyles.css``. + 3. Run the :djadmin:`collectstatic` management command:: - * The file ``/path/bar.jpg`` will not be accessible, because it doesn't - fall under the document root. + ./manage.py collectstatic -Of course, it's not compulsory to use a fixed string for the -``'document_root'`` value. You might wish to make that an entry in your -settings file and use the setting value there. That will allow you and -other developers working on the code to easily change the value as -required. For example, if we have a line in ``settings.py`` that says:: + This'll churn through your static file storage and move them into the + directory given by :setting:`STATICFILES_ROOT`. - STATIC_DOC_ROOT = '/path/to/media' + 4. Deploy that media. -...we could write the above :doc:`URLconf ` entry as:: + If you're using the built-in development server, you can quickly + serve static media locally by adding:: - from django.conf import settings - ... - (r'^site_media/(?P.*)$', 'django.views.static.serve', - {'document_root': settings.STATIC_DOC_ROOT}), + from django.contrib.staticfiles.urls import staticfiles_urlpatterns + urlpatterns += staticfiles_urlpatterns() -Be careful not to use the same path as your :setting:`ADMIN_MEDIA_PREFIX` (which defaults -to ``/media/``) as this will overwrite your URLconf entry. + to the bottom of your URLconf. See :ref:`staticfiles-development` for + details. -Directory listings -================== + When it comes time to deploy to production, :ref:`staticfiles-production` + covers some common deployment strategies for static files. -Optionally, you can pass the ``show_indexes`` parameter to the -:func:`~django.views.static.serve` view. This is ``False`` by default. If it's -``True``, Django will display file listings for directories. + However you choose to deploy those files, you'll probably need to refer + to them in your templates. The easiest method is to use the included + context processor which will allow template code like: -For example:: + .. code-block:: html+django - (r'^site_media/(?P.*)$', 'django.views.static.serve', - {'document_root': '/path/to/media', 'show_indexes': True}), + + +Of course, there are some serious problems with this: it doesn't work well in +development, and it makes it *very* hard to change where you've deployed your +media. If, for example, you wanted to switch to using a content delivery network +(CDN), then you'd need to change more or less every single template. + +A far better way is to use the value of the :setting:`STATICFILES_URL` setting +directly in your templates. This means that a switch of media servers only +requires changing that single value. Much better! + +``staticfiles`` inludes two built-in ways of getting at this setting in your +templates: a context processor and a template tag. - - - - - - - Index of {{ directory }} - - -

Index of {{ directory }}

-
    - {% for f in file_list %} -
  • {{ f }}
    • - {% endfor %} -
- - - -.. versionchanged:: 1.0.3 - Prior to Django 1.0.3, there was a bug in the view that provided directory - listings. The template that was loaded had to be called - ``static/directory_listing`` (with no ``.html`` extension). For backwards - compatibility with earlier versions, Django will still load templates with - the older (no extension) name, but it will prefer the - ``directory_index.html`` version. - -Limiting use to DEBUG=True -========================== - -Because URLconfs are just plain Python modules, you can use Python logic to -make the static-media view available only in development mode. This is a handy -trick to make sure the static-serving view doesn't slip into a production -setting by mistake. - -Do this by wrapping an ``if DEBUG`` statement around the -:func:`django.views.static.serve` inclusion. Here's a full example URLconf:: - - from django.conf.urls.defaults import * - from django.conf import settings - - urlpatterns = patterns('', - (r'^articles/2003/$', 'news.views.special_case_2003'), - (r'^articles/(?P\d{4})/$', 'news.views.year_archive'), - (r'^articles/(?P\d{4})/(?P\d{2})/$', 'news.views.month_archive'), - (r'^articles/(?P\d{4})/(?P\d{2})/(?P\d+)/$', 'news.views.article_detail'), +With a context processor +------------------------ + +The included context processor is the easy way. Simply make sure +``'django.contrib.staticfiles.context_processors.staticfiles'`` is in your +:setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're +editing that setting by hand it should look something like:: + + TEMPLATE_CONTEXT_PROCESSORS = ( + 'django.core.context_processors.debug', + 'django.core.context_processors.i18n', + 'django.contrib.auth.context_processors.auth', + 'django.contrib.messages.context_processors.messages', + 'django.contrib.staticfiles.context_processors.staticfiles', ) - if settings.DEBUG: - urlpatterns += patterns('', - (r'^site_media/(?P.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}), +Once that's done, you can refer to :setting:`STATICFILES_URL` in your templates: + +.. code-block:: html+django + + + +There's also a second form you can use to avoid extra processing if you need the +value multiple times: + +.. code-block:: html+django + + {% load staticfiles %} + {% get_staticfiles_prefix as STATIC_PREFIX %} + + + + +.. _staticfiles-development: + +Serving static files in development +=================================== + +The static files tools are mostly designed to help with getting static media +successfully deployed into production. This usually means a separate, dedicated +media server, which is a lot of overhead to mess with when developing locally. +Thus, the ``staticfiles`` app ships with a quick and dirty helper view that you +can use to serve media locally in development. + +To enable this view, you'll add a couple of lines to your URLconf. The first +line goes at the top of the file, and the last line at the bottom:: + + from django.contrib.staticfiles.urls import staticfiles_urlpatterns + + # ... the rest of your URLconf goes here ... + + urlpatterns += staticfiles_urlpatterns() + +This will inspect your :setting:`STATICFILES_URL` and +:setting:`STATICFILES_ROOT` settings and wire up the view to serve static media +accordingly. Remember to run :djadmin:`collectstatic` when your media changes; +the view only serves static files that have been collected. + +.. warning:: + + This will only work if :setting:`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**. + +For a few more details, including an alternate method of enabling this view, +see :ref:`staticfiles-development-view`. + +.. _staticfiles-production: + +Serving static files in production +================================== + +The basic outline of putting static files into production a simple: un the +:djadmin:`collectstatic` command when static media changes, then arrange for the +collected media directory (:setting:`STATICFILES_ROOT`) to be moved to the media +server and served. + +Of course, as with all deployment tasks, the devil's in the details. Every +production setup will be a bit different, so you'll need to adapt the basic +outline to fit your needs. Below are a few common patterns that might help. + +Serving the app and your static files from the same server +---------------------------------------------------------- + +If you want to serve your media from the same server that's already serving your +app, the basic outline gets modified to look something like: + + * Push your code up to the deployment server. + * On the server, run :djadmin:`collectmedia` to move all the media into + :setting:`STATICFILES_ROOT`. + * Point your web server at :setting:`STATICFILES_ROOT`. For example, here's + of :ref:`how to do this under Apache and mod_wsgi `. + +You'll probably want to automate this process, especially if you've got multiple +web servers. There's any number of ways to do this automation, but one option +that many Django developers enjoy is `Fabric`__. + +__ http://fabfile.org/ + +Below, and in the following sections, we'll show off a few example fabfiles +(i.e. Fabric scripts) that automate these media deployment options. The syntax +of a fabfile is fairly streightforward but won't be covered here; consult `Fabric's documentation`__, for a complete explanation of the syntax.. + +__ http://docs.fabfile.org/ + +So, a fabfile to deploy media to a couple of web servers might look something +like:: + + from fabric.api import * + + # Hosts to deploy onto + env.hosts = ['www1.example.com', 'www2.example.com'] + + # Where your project code lives on the server + env.project_root = '/home/www/myproject' + + def deploy_static(): + with cd(env.project_root): + run('./manage.py collectstatic') + +Serving static files from a dedicated media server +-------------------------------------------------- + +Most larger Django apps use a separate Web server -- i.e., one that's not also +running Django -- for serving media. This server often runs a different type of +web server -- faster but less full-featured. Some good choices are: + + * lighttpd_ + * Nginx_ + * TUX_ + * Cherokee_ + * A stripped-down version of Apache_ + +.. _lighttpd: http://www.lighttpd.net/ +.. _Nginx: http://wiki.nginx.org/Main +.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server +.. _Apache: http://httpd.apache.org/ +.. _Cherokee: http://www.cherokee-project.com/ + +Configuring these servers is out of scope of this document; check each server's +respective documentation for instructions. + +Since your media server won't be running Django, you'll need to modify the +deployment strategy to look something like: + + * When your media changes, run :djadmin:`collectstatic` locally. + * Push your local :setting:`STATICFILES_ROOT` up to the media server + into the directory that's being served. ``rsync`` is a good + choice for this step since it only needs to transfer the + bits of static media that have changed. + +Here's how this might look in a fabfile:: + + from fabric.api import * + from fabric.contrib import project + + # Where the static files get collected locally + env.local_static_root = '/tmp/static' + + # Where the static files should go remotely + env.remote_static_root = '/home/www/media.example.com' + + @roles('media') + def deploy_static(): + local('./manage.py collectstatic') + project.rysnc_project( + remote_dir = env.remote_static_root, + local_dir = env.local_static_root, + delete = True ) -This code is straightforward. It imports the settings and checks the value of -the :setting:`DEBUG` setting. If it evaluates to ``True``, then ``site_media`` -will be associated with the ``django.views.static.serve`` view. If not, then the -view won't be made available. +.. _staticfiles-from-cdn: + +Serving static media from a cloud service or CDN +------------------------------------------------ + +Another common tactic is to serve media from a cloud storage provider like +Amazon's S3__ and/or a CDN (content delivery network). This lets you ignore the +problems of serving media, and can often make for faster-loading webpages +(especially when using a CDN). + +When using these services, the basic workflow would look a bit like the above, +except that instead of using ``rsync`` to transfer your media to the server +you'd need to transfer the media to the storage provider or CDN. + +There's any number of ways you might do this, but if the provider has an API a +:doc:`custom file storage backend ` will make the +process incredibly simple. If you've written or are using a 3rd party custom +storage backend, you can tell :djadmin:`collectstatic` to use it by setting +:setting:`STATICFILES_STORAGE` to the storage engine. + +For example, if you've written an S3 storage backend in +``myproject.storage.S3Storage`` you could use it with:: + + STATICFILES_STORAGE = 'storages.backends.s3.S3Storage' + +Once that's done, all you have to do is run :djadmin:`collectstatic` and your +media would be pushed through your storage package up to S3. If you later needed +to swich to a different storage provider, it could be as simple as changing your +:setting:`STATICFILES_STORAGE` setting. + +For details on how you'd write one of these backends, +:doc:`/howto/custom-file-storage`. + +.. seealso:: -Of course, the catch here is that you'll have to remember to set ``DEBUG=False`` -in your production settings file. But you should be doing that anyway. + The `django-storages`__ project is a 3rd party app that provides many + storage backends for many common file storage APIs (including S3). + +__ http://s3.amazonaws.com/ +__ http://code.welldev.org/django-storages/wiki/S3Storage + +Upgrading from ``django-staticfiles`` +===================================== + +``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If +you're upgrading from `django-staticfiles`_ to ``django.contrib.staticfiles``, +you'll need to make a few changes: + + * Application files should now live in a ``static`` directory in each app + (`django-staticfiles`_ used the name ``media``, which was slightly + confusing). + + * The management commands ``build_static`` and ``resolve_static`` are now + called :djadmin:`collectstatic` and :djadmin:`findstatic`. + + * The settings ``STATIC_URL`` and ``STATIC_ROOT`` were renamed to + :setting:`STATICFILES_URL` and :setting:`STATICFILES_ROOT`. + + * The settings ``STATICFILES_PREPEND_LABEL_APPS``, + ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were + removed. + + * The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the new + :setting:`STATICFILES_FINDERS`. + + * The default for :setting:`STATICFILES_STORAGE` was renamed from + ``staticfiles.storage.StaticFileStorage`` to + ``staticfiles.storage.StaticFilesStorage`` + +Learn more +========== + +This document has covered the basics and some common usage patterns. For +complete details on all the settings, commands, template tags, and other pieces +include in ``django.contrib.staticfiles``, see :doc:`the statcfiles reference +`. \ No newline at end of file diff --git a/docs/index.txt b/docs/index.txt index e456d047ec..afa2e37f25 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -155,7 +155,7 @@ The development process :doc:`Apache/mod_python ` | :doc:`FastCGI/SCGI/AJP ` | :doc:`Apache authentication ` | - :doc:`Serving static files ` | + :doc:`Handling static files ` | :doc:`Tracking code errors by e-mail ` Other batteries included @@ -185,6 +185,7 @@ Other batteries included * :doc:`Signals ` * :doc:`Sitemaps ` * :doc:`Sites ` + * :doc:`Static Files ` * :doc:`Syndication feeds (RSS/Atom) ` * :doc:`Unicode in Django ` * :doc:`Web design helpers ` diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index 90edf72c94..5e308dc469 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -38,6 +38,7 @@ those packages have. redirects sitemaps sites + staticfiles syndication webdesign diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt new file mode 100644 index 0000000000..0a330a0fce --- /dev/null +++ b/docs/ref/contrib/staticfiles.txt @@ -0,0 +1,283 @@ +=================== +The staticfiles app +=================== + +.. module:: django.contrib.staticfiles + :synopsis: An app for handling static files. + +.. versionadded:: 1.3 + +``django.contrib.staticfiles`` collects media from each of your applications +(and any other places you specify) into a single location that can easily be +served in production. + +.. seealso:: + + For an introduction to the static files app and some usage examples, see + :doc:`/howto/static-files`. + +.. _staticfiles-settings: + +Settings +======== + +.. highlight:: python + +The following settings control the behavior of the static files app. Only +:setting:`STATICFILES_ROOT` is required, but you'll probably also need to +configure :setting:`STATICFILES_URL` as well. + +.. setting:: STATICFILES_ROOT + +STATICFILES_ROOT +---------------- + +Default: ``''`` (Empty string) + +The absolute path to the directory that holds static files:: + + STATICFILES_ROOT = "/home/example.com/static/" + +This is a **required setting** unless you've overridden +:setting:`STATICFILES_STORAGE` and are using a custom storage backend. + +.. setting:: STATICFILES_URL + +STATICFILES_URL +--------------- + +Default: ``'/static/'`` + +The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.:: + + STATICFILES_URL = '/site_media/static/' + +... or perhaps:: + + STATICFILES_URL = 'http://media.exmaple.com/' + +This should **always** have a trailing slash. + +.. setting:: STATICFILES_DIRS + +STATICFILES_DIRS +---------------- + +Default: ``[]`` + +This setting defines the additional locations the staticfiles app will traverse +if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the +:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the +static file serving view. + +It should be defined as a sequence of ``(prefix, path)`` tuples, e.g.:: + + STATICFILES_DIRS = ( + ('', '/home/special.polls.com/polls/media'), + ('', '/home/polls.com/polls/media'), + ('common', '/opt/webfiles/common'), + ) + +.. setting:: STATICFILES_STORAGE + +STATICFILES_STORAGE +------------------- + +Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'`` + +The file storage engine to use when collecting static files with the +:djadmin:`collectstatic` management command. + +For an example, see :ref:`staticfiles-from-cdn`. + +.. setting:: STATICFILES_FINDERS + +STATICFILES_FINDERS +------------------- + +Default:: + + ("django.contrib.staticfiles.finders.FileSystemFinder", + "django.contrib.staticfiles.finders.AppDirectoriesFinder") + +The list of finder backends that know how to find static files in +various locations. + +The default will find files stored in the :setting:`STATICFILES_DIRS` setting +(using :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a +``static`` subdirectory of each app (using +:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`) + +One finder is disabled by default: +:class:`django.contrib.staticfiles.finders.DefaultStorageFinder`. If added to +your :setting:`STATICFILES_FINDERS` setting, it will look for static files in +the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` +setting. + +.. note:: + + When using the :class:AppDirectoriesFinder` finder, make sure your apps can + be found by Django's app loading mechanism. Simply include a ``models`` + module (an empty ``models.py`` file suffices) and add the app to the + :setting:`INSTALLED_APPS` setting of your site. + +Static file finders are currently considered a private interface, and this +interface is thus undocumented. + +Management Commands +=================== + +.. highlight:: console + +``django.contrib.staticfiles`` exposes two management commands. + +collectstatic +------------- + +.. django-admin:: collectstatic + +Collects the static files into :setting:`STATICFILES_ROOT`. + +Duplicate file names are resolved in a similar way to how template resolution +works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from +earlier apps, and files from storage directories later in +:setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused, +the :djadmin:`findstatic` command can help show you where + +Files are searched by using the :ref:`enabled finders +`. The default is to look in all locations defined in +:ref:`staticfiles-dirs` and in the ``media`` directory of apps specified by the +:setting:`INSTALLED_APPS` setting. + +Some commonly used options are: + +``--noinput`` + Do NOT prompt the user for input of any kind. + +``-i PATTERN`` or ``--ignore=PATTERN`` + Ignore files or directories matching this glob-style pattern. Use multiple + times to ignore more. + +``-n`` or ``--dry-run`` + Do everything except modify the filesystem. + +``-l`` or ``--link`` + Create a symbolic link to each file instead of copying. + +``--no-default-ignore`` + Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'`` + and ``'*~'``. + +For a full list of options, refer to the commands own help by running:: + + $ python manage.py collectstatic --help + +findstatic +---------- + +.. django-admin:: findstatic + +Searches for one or more relative paths with the enabled finders. + +For example:: + + $ python manage.py findstatic css/base.css admin/js/core.js + /home/special.polls.com/core/media/css/base.css + /home/polls.com/core/media/css/base.css + /home/polls.com/src/django/contrib/admin/media/js/core.js + +By default, all matching locations are found. To only return the first match +for each relative path, use the ``--first`` option:: + + $ python manage.py findstatic css/base.css --first + /home/special.polls.com/core/media/css/base.css + +This is a debugging aid; it'll show you exactly which static file will be +collected for a given path. + +Other Helpers +============= + +The ``media`` context processor +------------------------------- + +.. function:: django.contrib.staticfiles.context_processors.staticfiles + +This context processor adds the :setting:`STATICFILES_URL` into each template +context as the variable ``{{ STATICFILES_URL }}``. To use it, make sure that +``'django.contrib.staticfiles.context_processors.staticfiles'`` appears +somewhere in your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. + +Remember, only templates rendered with :class:`~django.template.RequestContext` +will have acces to the data provided by this (and any) context processor. + +.. templatetag:: get_staticfiles_prefix + +The ``get_staticfiles_prefix`` templatetag +========================================== + +.. highlight:: html+django + +If you're not using :class:`~django.template.RequestContext`, or if you need +more control over exactly where and how :setting:`STATICFILES_URL` is injected +into the template, you can use the :ttag:`get_staticfiles_prefix` template tag +instead:: + + {% load staticfiles %} + + +There's also a second form you can use to avoid extra processing if you need the +value multiple times:: + + {% load staticfiles %} + {% get_staticfiles_prefix as STATIC_PREFIX %} + + + + +.. _staticfiles-development-view: + +Static file development view +---------------------------- + +.. highlight:: python + +.. function:: django.contrib.staticfiles.views.serve(request, path) + +This view function serves static media in in development. + +.. warning:: + + This view will only work if :setting:`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**. + +To use the view, add the following snippet to the end of your primary URL +configuration:: + + from django.conf import settings + + if settings.DEBUG: + urlpatterns = patterns('django.contrib.staticfiles.views', + url(r'^static/(?P.*)$', 'serve'), + ) + +Note, the begin of the pattern (``r'^static/'``) should be your +:setting:`STATICFILES_URL` setting. + +Since this is a bit finicky, there's also a helper function that'll do this for you: + +.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns() + +This will return the proper URL pattern for serving static files to your +already defined pattern list. Use it like this:: + + from django.contrib.staticfiles.urls import staticfiles_urlpatterns + + # ... the rest of your URLconf here ... + + urlpatterns += staticfiles_urlpatterns() + + diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 6ad5af9301..f0b4c562da 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1482,7 +1482,7 @@ Default:: ("django.contrib.auth.context_processors.auth", "django.core.context_processors.debug", "django.core.context_processors.i18n", - "django.core.context_processors.media", + "django.contrib.staticfiles.context_processors.staticfiles", "django.contrib.messages.context_processors.messages") A tuple of callables that are used to populate the context in ``RequestContext``. diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 2ac4e653c4..4589084ac2 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -289,6 +289,8 @@ you'll see below. Subclassing Context: RequestContext ----------------------------------- +.. class:: django.template.RequestContext + Django comes with a special ``Context`` class, ``django.template.RequestContext``, that acts slightly differently than the normal ``django.template.Context``. The first difference is that it takes an @@ -309,7 +311,7 @@ and return a dictionary of items to be merged into the context. By default, ("django.contrib.auth.context_processors.auth", "django.core.context_processors.debug", "django.core.context_processors.i18n", - "django.core.context_processors.media", + "django.contrib.staticfiles.context_processors.staticfiles", "django.contrib.messages.context_processors.messages") .. versionadded:: 1.2 @@ -432,6 +434,11 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every ``RequestContext`` will contain a variable ``MEDIA_URL``, providing the value of the :setting:`MEDIA_URL` setting. +.. versionchanged:: 1.3 + This context processor has been moved to the new :ref:`staticfiles` app. + Please use the new ``django.contrib.staticfiles.context_processors.staticfiles`` + context processor. + django.core.context_processors.csrf ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.3