Fixed #14693, #14709 -- Backwards incompatible change to rectify the confusion around the STATICFILES_URL and STATICFILES_ROOT settings.

  * Two new global settings that will be used by -- **but are not limited to** -- the staticfiles app: STATIC_ROOT and STATIC_URL.

  * Moving the 'django.contrib.staticfiles.templatetags.staticfiles' template tag to the core ('django.templatetags.static') and renaming it to 'get_static_prefix'.

  * Moving the context processor 'django.contrib.staticfiles.context_processors.staticfiles' to the core ('django.core.context_processors.static') and renaming it to 'static'.

  * Paths in media definitions will use STATIC_URL as the prefix if the value is not None, and falls back to the previously used MEDIA_URL.

Thanks again to the community for constructive criticism and Carl and Russ for sanity-inducing discussions on IRC.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14592 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 32 insertions, 9 deletions

diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt
index 548095d83b..b0f3c86107 100644
--- a/docs/topics/forms/media.txt
+++ b/docs/topics/forms/media.txt
@@ -190,28 +190,51 @@ also be defined in a dynamic fashion::
 See the section on `Media objects`_ for more details on how to construct
 return values for dynamic media properties.
 
+.. _form-media-paths:
+
 Paths in media definitions
 --------------------------
 
+.. versionchanged:: 1.3
+
 Paths used to specify media can be either relative or absolute. If a path
 starts with '/', 'http://' or 'https://', it will be interpreted as an absolute
 path, and left as-is. All other paths will be prepended with the value of
-``settings.MEDIA_URL``. For example, if the MEDIA_URL for your site was
-``http://media.example.com/``::
+the appropriate prefix.
 
-    class CalendarWidget(forms.TextInput):
-        class Media:
-            css = {
-                'all': ('/css/pretty.css',),
-            }
-            js = ('animations.js', 'http://othersite.com/actions.js')
+As part of the introduction of the
+:doc:`staticfiles app </ref/contrib/staticfiles>` two new settings were added
+to refer to "static content" (images, CSS, Javascript, etc.) that are needed
+to render a complete web page: :setting:`STATIC_URL` and :setting:`STATIC_ROOT`.
+
+To find the appropriate prefix to use, Django will check if the
+:setting:`STATIC_URL` setting is not ``None`` and automatically fall back
+to using :setting:`MEDIA_URL`. For example, if the :setting:`MEDIA_URL` for
+your site was ``'http://uploads.example.com/'`` and :setting:`STATIC_URL`
+was ``None``::
+
+    >>> class CalendarWidget(forms.TextInput):
+            class Media:
+                css = {
+                    'all': ('/css/pretty.css',),
+                }
+                js = ('animations.js', 'http://othersite.com/actions.js')
 
     >>> w = CalendarWidget()
     >>> print w.media
     <link href="/css/pretty.css" type="text/css" media="all" rel="stylesheet" />
-    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
+    <script type="text/javascript" src="http://uploads.example.com/animations.js"></script>
+    <script type="text/javascript" src="http://othersite.com/actions.js"></script>
+
+But if :setting:`STATIC_URL` is ``'http://static.example.com/'``::
+
+    >>> w = CalendarWidget()
+    >>> print w.media
+    <link href="/css/pretty.css" type="text/css" media="all" rel="stylesheet" />
+    <script type="text/javascript" src="http://static.example.com/animations.js"></script>
     <script type="text/javascript" src="http://othersite.com/actions.js"></script>
 
+
 Media objects
 -------------