docs/static_files.txt

   1 =========================
   2 How to serve static files
   3 =========================
   4
   5 Django itself doesn't serve static (media) files, such as images, style sheets,
   6 or video. It leaves that job to whichever Web server you choose.
   7
   8 The reasoning here is that standard Web servers, such as Apache_ and lighttpd_,
   9 are much more fine-tuned at serving static files than a Web application
  10 framework.
  11
  12 With that said, Django does support static files **during development**. Use
  13 the view ``django.views.static.serve`` to serve media files.
  14
  15 .. _Apache: http://httpd.apache.org/
  16 .. _lighttpd: http://www.lighttpd.net/
  17
  18 The big, fat disclaimer
  19 =======================
  20
  21 Using this method is **inefficient** and **insecure**. Do not use this in a
  22 production setting. Use this only for development.
  23
  24 For information on serving static files in an Apache production environment,
  25 see the `Django mod_python documentation`_.
  26
  27 .. _Django mod_python documentation: http://www.djangoproject.com/documentation/modpython/#serving-media-files
  28
  29 How to do it
  30 ============
  31
  32 Just put this in your URLconf_::
  33
  34     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}),
  35
  36 ...where ``site_media`` is the URL where your media will be rooted, and
  37 ``/path/to/media`` is the filesystem root for your media.
  38
  39 You must pass a ``document_root`` parameter to indicate the filesystem root.
  40
  41 Examples:
  42
  43     * The file ``/path/to/media/foo.jpg`` will be made available at the URL
  44       ``/site_media/foo.jpg``.
  45
  46     * The file ``/path/to/media/css/mystyles.css`` will be made available
  47       at the URL ``/site_media/css/mystyles.css``.
  48
  49     * The file ``/path/bar.jpg`` will not be accessible, because it doesn't
  50       fall under the document root.
  51
  52 .. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
  53
  54 Directory listings
  55 ==================
  56
  57 Optionally, you can pass a ``show_indexes`` parameter to the ``static.serve``
  58 view. This is ``False`` by default. If it's ``True``, Django will display file
  59 listings for directories.
  60
  61 Example::
  62
  63     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/media', 'show_indexes': True}),
  64
  65 You can customize the index view by creating a template called
  66 ``static/directory_index``. That template gets two objects in its context:
  67
  68     * ``directory`` -- the directory name (a string)
  69     * ``file_list`` -- a list of file names (as strings) in the directory
  70
  71 Here's the default ``static/directory_index`` template::
  72
  73     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  74     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  75     <head>
  76         <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  77         <meta http-equiv="Content-Language" content="en-us" />
  78         <meta name="robots" content="NONE,NOARCHIVE" />
  79         <title>Index of {{ directory }}</title>
  80     </head>
  81     <body>
  82         <h1>Index of {{ directory }}</h1>
  83         <ul>
  84         {% for f in file_list %}
  85         <li><a href="{{ f }}">{{ f }}</a></li>
  86         {% endfor %}
  87         </ul>
  88     </body>
  89     </html>
  90
  91 Limiting use to DEBUG=True
  92 ==========================
  93
  94 Because URLconfs are just plain Python modules, you can use Python logic to
  95 make the static-media view available only in development mode. This is a handy
  96 trick to make sure the static-serving view doesn't slip into a production
  97 setting by mistake.
  98
  99 Do this by wrapping an ``if DEBUG`` statement around the
 100 ``django.views.static.serve`` inclusion. Here's a full example URLconf::
 101
 102     from django.conf.urls.defaults import *
 103     from django.conf.settings import DEBUG
 104
 105     urlpatterns = patterns('',
 106         (r'^/articles/2003/$', 'news.views.special_case_2003'),
 107         (r'^/articles/(?P<year>\d{4})/$', 'news.views.year_archive'),
 108         (r'^/articles/(?P<year>\d{4})/(?P<month>\d{2})/$', 'news.views.month_archive'),
 109         (r'^/articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d+)/$', 'news.views.article_detail'),
 110     )
 111
 112     if DEBUG:
 113         urlpatterns += patterns('',
 114             (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}),
 115         )
 116
 117 This code is straightforward. It imports the `DEBUG setting`_ and checks its
 118 value. If it evaluates to ``True``, then ``site_media`` will be associated with
 119 the ``django.views.static.serve`` view. If not (``DEBUG == False``), then the
 120 view won't be made available.
 121
 122 Of course, the catch here is that you'll have to remember to set ``DEBUG=False``
 123 in your production settings file. But you should be doing that anyway.
 124
 125 .. _DEBUG setting: http://www.djangoproject.com/documentation/settings/#debug