diff options
Diffstat (limited to 'parts/django/docs/howto/static-files.txt')
| -rw-r--r-- | parts/django/docs/howto/static-files.txt | 162 |
1 files changed, 0 insertions, 162 deletions
diff --git a/parts/django/docs/howto/static-files.txt b/parts/django/docs/howto/static-files.txt deleted file mode 100644 index c3692d5..0000000 --- a/parts/django/docs/howto/static-files.txt +++ /dev/null @@ -1,162 +0,0 @@ -========================= -How to serve static files -========================= - -.. module:: django.views.static - :synopsis: Serving of static files during development. - -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. - -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. - -With that said, Django does support static files **during development**. You can -use the :func:`django.views.static.serve` view to serve media files. - -.. _Apache: http://httpd.apache.org/ -.. _lighttpd: http://www.lighttpd.net/ -.. _Cherokee: http://www.cherokee-project.com/ - -.. seealso:: - - If you just need to serve the admin media from a nonstandard location, see - the :djadminopt:`--adminmedia` parameter to :djadmin:`runserver`. - -The big, fat disclaimer -======================= - -Using this method is **inefficient** and **insecure**. Do not use this in a -production setting. Use this only for development. - -For information on serving static files in an Apache production environment, -see the :ref:`Django mod_python documentation <serving-media-files>`. - -How to do it -============ - -Here's the formal definition of the :func:`~django.views.static.serve` view: - -.. function:: def serve(request, path, document_root, show_indexes=False) - -To use it, just put this in your :doc:`URLconf </topics/http/urls>`:: - - (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', - {'document_root': '/path/to/media'}), - -...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. - -Given the above URLconf: - - * The file ``/path/to/media/foo.jpg`` will be made available at the URL - ``/site_media/foo.jpg``. - - * The file ``/path/to/media/css/mystyles.css`` will be made available - at the URL ``/site_media/css/mystyles.css``. - - * The file ``/path/bar.jpg`` will not be accessible, because it doesn't - fall under the document root. - -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:: - - STATIC_DOC_ROOT = '/path/to/media' - -...we could write the above :doc:`URLconf </topics/http/urls>` entry as:: - - from django.conf import settings - ... - (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', - {'document_root': settings.STATIC_DOC_ROOT}), - -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. - -Directory listings -================== - -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. - -For example:: - - (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', - {'document_root': '/path/to/media', 'show_indexes': True}), - -You can customize the index view by creating a template called -``static/directory_index.html``. That template gets two objects in its context: - - * ``directory`` -- the directory name (a string) - * ``file_list`` -- a list of file names (as strings) in the directory - -Here's the default ``static/directory_index.html`` template: - -.. code-block:: html+django - - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> - <head> - <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> - <meta http-equiv="Content-Language" content="en-us" /> - <meta name="robots" content="NONE,NOARCHIVE" /> - <title>Index of {{ directory }}</title> - </head> - <body> - <h1>Index of {{ directory }}</h1> - <ul> - {% for f in file_list %} - <li><a href="{{ f }}">{{ f }}</a></li> - {% endfor %} - </ul> - </body> - </html> - -.. 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<year>\d{4})/$', 'news.views.year_archive'), - (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', 'news.views.month_archive'), - (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d+)/$', 'news.views.article_detail'), - ) - - if settings.DEBUG: - urlpatterns += patterns('', - (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}), - ) - -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. - -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. |