From a26034ffbf8951276b79ccb298423bc809246637 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Mon, 14 Feb 2011 01:42:26 +0000 Subject: Fixes #15270 -- Moved back the serve view to django.views.static due to dependency conflicts with the contrib app staticfiles (reverts parts of r14293). Added a helper function that generates URL patterns for serving static and media files during development. Thanks to Carl for reviewing the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@15530 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/static-files.txt | 71 +++++++++++++++++++++++++++++++++++----- docs/ref/contrib/staticfiles.txt | 28 ---------------- 2 files changed, 62 insertions(+), 37 deletions(-) (limited to 'docs') diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index 94e04bb738..3faeaeba41 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -2,8 +2,6 @@ Managing static files ===================== -.. currentmodule:: django.contrib.staticfiles - .. versionadded:: 1.3 Django developers mostly concern themselves with the dynamic parts of web @@ -109,10 +107,9 @@ the framework see :doc:`the staticfiles reference `. :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and :setting:`STATIC_URL`. You will need to arrange for serving of files in :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with - user-uploaded files at all. You can, however, use ``staticfiles``' - :func:`~django.contrib.staticfiles.views.serve` view for serving - :setting:`MEDIA_ROOT` in development; see - :ref:`staticfiles-serve-other-directories`. + user-uploaded files at all. You can, however, use + :func:`~django.views.static.serve` view for serving :setting:`MEDIA_ROOT` + in development; see :ref:`staticfiles-other-directories`. .. _staticfiles-in-templates: @@ -241,8 +238,64 @@ files in app directories. :setting:`STATIC_URL` setting can't be empty or a full URL, such as ``http://static.example.com/``. -For a few more details, including an alternate method of enabling this view, -see :ref:`staticfiles-development-view`. +For a few more details on how the ``staticfiles`` can be used during +development, see :ref:`staticfiles-development-view`. + +.. _staticfiles-other-directories: + +Serving other directories +------------------------- + +.. currentmodule:: django.views.static +.. function:: serve(request, path, document_root, show_indexes=False) + +There may be files other than your project's static assets that, for +convenience, you'd like to have Django serve for you in local development. +The :func:`~django.views.static.serve` view can be used to serve any directory +you give it. (Again, this view is **not** hardened for production +use, and should be used only as a development aid; you should serve these files +in production using a real front-end webserver). + +The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`. +``staticfiles`` is intended for static assets and has no built-in handling +for user-uploaded files, but you can have Django serve your +:setting:`MEDIA_ROOT` by appending something like this to your URLconf:: + + from django.conf import settings + + # ... the rest of your URLconf goes here ... + + if settings.DEBUG: + urlpatterns += patterns('', + url(r'^media/(?P.*)$', 'django.views.static', { + 'document_root': settings.MEDIA_ROOT, + }), + ) + +Note, the snippet assumes your :setting:`MEDIA_URL` has a value of +``'/media/'``. This will call the :func:`~django.views.static.serve` view, +passing in the path from the URLconf and the (required) ``document_root`` +parameter. + +.. currentmodule:: django.conf.urls.static +.. function:: static(prefix, view='django.views.static.serve', **kwargs) + +Since it can become a bit cumbersome to define this URL pattern, Django +ships with a small URL helper function +:func:`~django.conf.urls.static.static` that taks as parameters the prefix +such as :setting:`MEDIA_URL` and a dotted path to a view, such as +``'django.views.static.serve'``. Any other function parameter will be +transparently passed to the view. + +An example for serving :setting:`MEDIA_URL` (``'/media/'``) during +development:: + + from django.conf import settings + from django.conf.urls.static import static + + urlpatterns = patterns('', + # ... the rest of your URLconf goes here ... + ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) .. _staticfiles-production: @@ -395,7 +448,7 @@ Upgrading from ``django-staticfiles`` ===================================== ``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If -you're upgrading from `django-staticfiles`_ < ``1.0``` (e.g. ``0.3.4``) to +you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to ``django.contrib.staticfiles``, you'll need to make a few changes: * Application files should now live in a ``static`` directory in each app diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index dd26fe535b..b06620d085 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -317,31 +317,3 @@ already defined pattern list. Use it like this:: This helper function will only work if :setting:`DEBUG` is ``True`` and your :setting:`STATIC_URL` setting is neither empty nor a full URL such as ``http://static.example.com/``. - -.. _staticfiles-serve-other-directories: - -Serving other directories -""""""""""""""""""""""""" - -There may be files other than your project's static assets that, for -convenience, you'd like to have Django serve for you in local development. The -:func:`~django.contrib.staticfiles.views.serve` view can be used to serve any -directory you give it. (Again, this view is **not** hardened for production -use, and should be used only as a development aid; you should serve these files -in production using a real front-end webserver). - -The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`. -``staticfiles`` is intended for static assets and has no built-in handling for -user-uploaded files, but you can have Django serve your :setting:`MEDIA_ROOT` -by appending something like this to your URLconf:: - - from django.conf import settings - - if settings.DEBUG: - urlpatterns += patterns('django.contrib.staticfiles.views', - url(r'^media/(?P.*)$', 'serve', - {'document_root': settings.MEDIA_ROOT}), - ) - -This snippet assumes you've also set your :setting:`MEDIA_URL` (in development) -to ``/media/``. -- cgit v1.3