|
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: ../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: ../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 import settings |
|
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 settings.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 settings and checks the value of |
|
118 the ``DEBUG`` setting. If it evaluates to ``True``, then ``site_media`` will be |
|
119 associated with the ``django.views.static.serve`` view. If not |
|
120 (``DEBUG == False``), then the 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: ../settings/#debug |