|
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. |