1 =========================

     2 How to serve static files

     3 =========================

     4 

     5 .. module:: django.views.static

     6    :synopsis: Serving of static files during development.

     7 

     8 Django itself doesn't serve static (media) files, such as images, style sheets,

     9 or video. It leaves that job to whichever Web server you choose.

    10 

    11 The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and

    12 Cherokee_, are much more fine-tuned at serving static files than a Web

    13 application framework.

    14 

    15 With that said, Django does support static files **during development**. You can

    16 use the :func:`django.views.static.serve` view to serve media files.

    17 

    18 .. _Apache: http://httpd.apache.org/

    19 .. _lighttpd: http://www.lighttpd.net/

    20 .. _Cherokee: http://www.cherokee-project.com/

    21 

    22 .. seealso::

    23 

    24     If you just need to serve the admin media from a nonstandard location, see

    25     the :djadminopt:`--adminmedia` parameter to :djadmin:`runserver`.

    26 

    27 The big, fat disclaimer

    28 =======================

    29 

    30 Using this method is **inefficient** and **insecure**. Do not use this in a

    31 production setting. Use this only for development.

    32 

    33 For information on serving static files in an Apache production environment,

    34 see the :ref:`Django mod_python documentation <serving-media-files>`.

    35 

    36 How to do it

    37 ============

    38 

    39 Here's the formal definition of the :func:`~django.views.static.serve` view:

    40 

    41 .. function:: def serve(request, path, document_root, show_indexes=False)

    42 

    43 To use it, just put this in your :doc:`URLconf </topics/http/urls>`::

    44 

    45     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',

    46             {'document_root': '/path/to/media'}),

    47 

    48 ...where ``site_media`` is the URL where your media will be rooted, and

    49 ``/path/to/media`` is the filesystem root for your media. This will call the

    50 :func:`~django.views.static.serve` view, passing in the path from the URLconf

    51 and the (required) ``document_root`` parameter.

    52 

    53 Given the above URLconf:

    54 

    55     * The file ``/path/to/media/foo.jpg`` will be made available at the URL

    56       ``/site_media/foo.jpg``.

    57 

    58     * The file ``/path/to/media/css/mystyles.css`` will be made available

    59       at the URL ``/site_media/css/mystyles.css``.

    60 

    61     * The file ``/path/bar.jpg`` will not be accessible, because it doesn't

    62       fall under the document root.

    63 

    64 Of course, it's not compulsory to use a fixed string for the

    65 ``'document_root'`` value. You might wish to make that an entry in your

    66 settings file and use the setting value there. That will allow you and

    67 other developers working on the code to easily change the value as

    68 required. For example, if we have a line in ``settings.py`` that says::

    69 

    70     STATIC_DOC_ROOT = '/path/to/media'

    71 

    72 ...we could write the above :doc:`URLconf </topics/http/urls>` entry as::

    73 

    74     from django.conf import settings

    75     ...

    76     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',

    77             {'document_root': settings.STATIC_DOC_ROOT}),

    78 

    79 Be careful not to use the same path as your :setting:`ADMIN_MEDIA_PREFIX` (which defaults

    80 to ``/media/``) as this will overwrite your URLconf entry.

    81 

    82 Directory listings

    83 ==================

    84 

    85 Optionally, you can pass the ``show_indexes`` parameter to the

    86 :func:`~django.views.static.serve` view. This is ``False`` by default. If it's

    87 ``True``, Django will display file listings for directories.

    88 

    89 For example::

    90 

    91     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',

    92             {'document_root': '/path/to/media', 'show_indexes': True}),

    93 

    94 You can customize the index view by creating a template called

    95 ``static/directory_index.html``. That template gets two objects in its context:

    96 

    97     * ``directory`` -- the directory name (a string)

    98     * ``file_list`` -- a list of file names (as strings) in the directory

    99 

   100 Here's the default ``static/directory_index.html`` template:

   101 

   102 .. code-block:: html+django

   103 

   104     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

   105     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

   106     <head>

   107         <meta http-equiv="Content-type" content="text/html; charset=utf-8" />

   108         <meta http-equiv="Content-Language" content="en-us" />

   109         <meta name="robots" content="NONE,NOARCHIVE" />

   110         <title>Index of {{ directory }}</title>

   111     </head>

   112     <body>

   113         <h1>Index of {{ directory }}</h1>

   114         <ul>

   115         {% for f in file_list %}

   116         <li><a href="{{ f }}">{{ f }}</a></li>

   117         {% endfor %}

   118         </ul>

   119     </body>

   120     </html>

   121 

   122 .. versionchanged:: 1.0.3

   123     Prior to Django 1.0.3, there was a bug in the view that provided directory

   124     listings. The template that was loaded had to be called

   125     ``static/directory_listing`` (with no ``.html`` extension). For backwards

   126     compatibility with earlier versions, Django will still load templates with

   127     the older (no extension) name, but it will prefer the

   128     ``directory_index.html`` version.

   129 

   130 Limiting use to DEBUG=True

   131 ==========================

   132 

   133 Because URLconfs are just plain Python modules, you can use Python logic to

   134 make the static-media view available only in development mode. This is a handy

   135 trick to make sure the static-serving view doesn't slip into a production

   136 setting by mistake.

   137 

   138 Do this by wrapping an ``if DEBUG`` statement around the

   139 :func:`django.views.static.serve` inclusion. Here's a full example URLconf::

   140 

   141     from django.conf.urls.defaults import *

   142     from django.conf import settings

   143 

   144     urlpatterns = patterns('',

   145         (r'^articles/2003/$', 'news.views.special_case_2003'),

   146         (r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),

   147         (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', 'news.views.month_archive'),

   148         (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d+)/$', 'news.views.article_detail'),

   149     )

   150 

   151     if settings.DEBUG:

   152         urlpatterns += patterns('',

   153             (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}),

   154         )

   155 

   156 This code is straightforward. It imports the settings and checks the value of

   157 the :setting:`DEBUG` setting. If it evaluates to ``True``, then ``site_media``

   158 will be associated with the ``django.views.static.serve`` view. If not, then the

   159 view won't be made available.

   160 

   161 Of course, the catch here is that you'll have to remember to set ``DEBUG=False``

   162 in your production settings file. But you should be doing that anyway.