diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/static-files.txt | 60 | ||||
| -rw-r--r-- | docs/man/django-admin.1 | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/staticfiles.txt | 122 | ||||
| -rw-r--r-- | docs/ref/django-admin.txt | 29 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 60 | ||||
| -rw-r--r-- | docs/ref/templates/api.txt | 13 | ||||
| -rw-r--r-- | docs/releases/1.3-alpha-1.txt | 6 | ||||
| -rw-r--r-- | docs/releases/1.3-alpha-2.txt | 45 | ||||
| -rw-r--r-- | docs/releases/1.3.txt | 2 | ||||
| -rw-r--r-- | docs/releases/index.txt | 1 | ||||
| -rw-r--r-- | docs/topics/forms/media.txt | 41 |
11 files changed, 234 insertions, 147 deletions
diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index 37f1fc361d..e27cb99901 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -50,12 +50,12 @@ Here's the basic usage in a nutshell: First, you'll need to make sure that ``django.contrib.staticfiles`` is in your :setting:`INSTALLED_APPS`. - Next, you'll need to edit :setting:`STATICFILES_ROOT` to point to where + Next, you'll need to edit :setting:`STATIC_ROOT` to point to where you'd like your static media stored. For example:: - STATICFILES_ROOT = "/home/jacob/projects/mysite.com/static_media" + STATIC_ROOT = "/home/jacob/projects/mysite.com/static_media" - You may also want to set the :setting:`STATICFILES_URL` setting at this + You may also want to set the :setting:`STATIC_URL` setting at this time, though the default value (of ``/static/``) is perfect for local development. @@ -69,7 +69,7 @@ Here's the basic usage in a nutshell: ./manage.py collectstatic This'll churn through your static file storage and move them into the - directory given by :setting:`STATICFILES_ROOT`. (This is not necessary + directory given by :setting:`STATIC_ROOT`. (This is not necessary in local development if you are using :djadmin:`runserver` or adding ``staticfiles_urlpatterns`` to your URLconf; see below). @@ -78,7 +78,7 @@ Here's the basic usage in a nutshell: If you're using the built-in development server (the :djadmin:`runserver` management command) and have the :setting:`DEBUG` setting set to ``True``, your staticfiles will automatically be served - from :setting:`STATICFILES_URL` in development. + from :setting:`STATIC_URL` in development. If you are using some other server for local development, you can quickly serve static media locally by adding:: @@ -98,7 +98,7 @@ Here's the basic usage in a nutshell: .. code-block:: html+django - <img src="{{ STATICFILES_URL }}images/hi.jpg /> + <img src="{{ STATIC_URL }}images/hi.jpg /> See :ref:`staticfiles-in-templates` for more details, including an alternate method (using a template tag). @@ -115,7 +115,7 @@ the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`. app is to make it easier to keep static files separate from user-uploaded files. For this reason, you will probably want to make your :setting:`MEDIA_ROOT` and :setting:`MEDIA_URL` different from your - :setting:`STATICFILES_ROOT` and :setting:`STATICFILES_URL`. You will need to + :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 media at all. @@ -136,7 +136,7 @@ development, and it makes it *very* hard to change where you've deployed your media. If, for example, you wanted to switch to using a content delivery network (CDN), then you'd need to change more or less every single template. -A far better way is to use the value of the :setting:`STATICFILES_URL` setting +A far better way is to use the value of the :setting:`STATIC_URL` setting directly in your templates. This means that a switch of media servers only requires changing that single value. Much better! @@ -147,7 +147,7 @@ With a context processor ------------------------ The included context processor is the easy way. Simply make sure -``'django.contrib.staticfiles.context_processors.staticfiles'`` is in your +``'django.core.context_processors.static'`` is in your :setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're editing that setting by hand it should look something like:: @@ -155,18 +155,18 @@ editing that setting by hand it should look something like:: 'django.core.context_processors.debug', 'django.core.context_processors.i18n', 'django.core.context_processors.media', + 'django.core.context_processors.static', 'django.contrib.auth.context_processors.auth', 'django.contrib.messages.context_processors.messages', - 'django.contrib.staticfiles.context_processors.staticfiles', ) -Once that's done, you can refer to :setting:`STATICFILES_URL` in your templates: +Once that's done, you can refer to :setting:`STATIC_URL` in your templates: .. code-block:: html+django - <img src="{{ STATICFILES_URL }}images/hi.jpg /> + <img src="{{ STATIC_URL }}images/hi.jpg /> -If ``{{ STATICFILES_URL }}`` isn't working in your template, you're probably not +If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not using :class:`~django.template.RequestContext` when rendering the template. As a brief refresher, context processors add variables into the contexts of @@ -180,23 +180,23 @@ To see how that works, and to read more details, check out With a template tag ------------------- -The second option is the :ttag:`get_staticfiles_prefix` template tag. You can +The second option is the :ttag:`get_static_prefix` template tag. You can use this if you're not using :class:`~django.template.RequestContext`, or if you -need more control over exactly where and how :setting:`STATICFILES_URL` is +need more control over exactly where and how :setting:`STATIC_URL` is injected into the template. Here's an example: .. code-block:: html+django - {% load staticfiles %} - <img src="{% get_staticfiles_prefix %}images/hi.jpg" /> + {% load static %} + <img src="{% get_static_prefix %}images/hi.jpg" /> There's also a second form you can use to avoid extra processing if you need the value multiple times: .. code-block:: html+django - {% load staticfiles %} - {% get_staticfiles_prefix as STATIC_PREFIX %} + {% load static %} + {% get_static_prefix as STATIC_PREFIX %} <img src="{{ STATIC_PREFIX }}images/hi.jpg" /> <img src="{{ STATIC_PREFIX }}images/hi2.jpg" /> @@ -213,7 +213,7 @@ Thus, the ``staticfiles`` app ships with a quick and dirty helper view that you can use to serve files locally in development. This view is automatically enabled and will serve your static files at -:setting:`STATICFILES_URL` when you use the built-in :djadmin:`runserver`. +:setting:`STATIC_URL` when you use the built-in :djadmin:`runserver`. To enable this view if you are using some other server for local development, you'll add a couple of lines to your URLconf. The first line goes at the top of @@ -225,11 +225,11 @@ the file, and the last line at the bottom:: urlpatterns += staticfiles_urlpatterns() -This will inspect your :setting:`STATICFILES_URL` and -:setting:`STATICFILES_ROOT` settings and wire up the view to serve static media +This will inspect your :setting:`STATIC_URL` and +:setting:`STATIC_ROOT` settings and wire up the view to serve static media accordingly. Don't forget to set the :setting:`STATICFILES_DIRS` setting appropriately to let ``django.contrib.staticfiles`` know where to look for -files. +(additional) files. .. warning:: @@ -239,6 +239,9 @@ files. **insecure**. This is only intended for local development, and should **never be used in production**. + Additionally, your :setting:`STATIC_URL` setting can't be either 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`. @@ -249,7 +252,7 @@ Serving static files in production The basic outline of putting static files into production is simple: run the :djadmin:`collectstatic` command when static media changes, then arrange for the -collected media directory (:setting:`STATICFILES_ROOT`) to be moved to the media +collected media directory (:setting:`STATIC_ROOT`) to be moved to the media server and served. Of course, as with all deployment tasks, the devil's in the details. Every @@ -264,8 +267,8 @@ app, the basic outline gets modified to look something like: * Push your code up to the deployment server. * On the server, run :djadmin:`collectstatic` to move all the media into - :setting:`STATICFILES_ROOT`. - * Point your web server at :setting:`STATICFILES_ROOT`. For example, here's + :setting:`STATIC_ROOT`. + * Point your web server at :setting:`STATIC_ROOT`. For example, here's :ref:`how to do this under Apache and mod_wsgi <serving-media-files>`. You'll probably want to automate this process, especially if you've got multiple @@ -322,7 +325,7 @@ Since your media server won't be running Django, you'll need to modify the deployment strategy to look something like: * When your media changes, run :djadmin:`collectstatic` locally. - * Push your local :setting:`STATICFILES_ROOT` up to the media server + * Push your local :setting:`STATIC_ROOT` up to the media server into the directory that's being served. ``rsync`` is a good choice for this step since it only needs to transfer the bits of static media that have changed. @@ -403,9 +406,6 @@ you'll need to make a few changes: * The management commands ``build_static`` and ``resolve_static`` are now called :djadmin:`collectstatic` and :djadmin:`findstatic`. - * The settings ``STATIC_URL`` and ``STATIC_ROOT`` were renamed to - :setting:`STATICFILES_URL` and :setting:`STATICFILES_ROOT`. - * The settings ``STATICFILES_PREPEND_LABEL_APPS``, ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were removed. diff --git a/docs/man/django-admin.1 b/docs/man/django-admin.1 index 2197af6650..f9b530a77e 100644 --- a/docs/man/django-admin.1 +++ b/docs/man/django-admin.1 @@ -165,7 +165,7 @@ Do not prompt the user for input. Disable the development server's auto\-reloader. .TP .I \-\-nostatic -Disable automatic serving of static files from STATICFILES_URL. +Disable automatic serving of static files from STATIC_URL. .TP .I \-\-insecure Enables serving of static files even if DEBUG is False. diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index f82fd79024..2cd2282f4e 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -23,48 +23,11 @@ Settings .. highlight:: python -The following settings control the behavior of the staticfiles app. Only -:setting:`STATICFILES_ROOT` is required, but you'll probably also need to -configure :setting:`STATICFILES_URL` as well. - -.. setting:: STATICFILES_ROOT - -STATICFILES_ROOT ----------------- - -Default: ``''`` (Empty string) - -The absolute path to the directory that the :djadmin:`collectstatic` management -command will collect static files into, for serving from -:setting:`STATICFILES_URL`:: - - STATICFILES_ROOT = "/home/example.com/static/" - -This is a **required setting** unless you've overridden -:setting:`STATICFILES_STORAGE` and are using a custom storage backend. - -This is not a place to store your static files permanently under version -control; you should do that in directories that will be found by your -:setting:`STATICFILES_FINDERS` (by default, per-app ``static/`` subdirectories, -and any directories you include in :setting:`STATICFILES_DIRS`). Files from -those locations will be collected into :setting:`STATICFILES_ROOT`. - -.. setting:: STATICFILES_URL - -STATICFILES_URL ---------------- - -Default: ``'/static/'`` - -The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.:: - - STATICFILES_URL = '/site_media/static/' - -... or perhaps:: - - STATICFILES_URL = 'http://static.example.com/' +.. note:: -This should **always** have a trailing slash. + The following settings control the behavior of the staticfiles app. + Configuring the global settings :setting:`STATIC_ROOT` and + :setting:`STATIC_URL` is **required**. .. setting:: STATICFILES_DIRS @@ -98,7 +61,7 @@ tuples, e.g.:: With this configuration, the :djadmin:`collectstatic` management command would for example collect the stats files in a ``'downloads'`` directory. So -assuming you have :setting:`STATICFILES_URL` set ``'/static/'``, this would +assuming you have :setting:`STATIC_URL` set ``'/static/'``, this would allow you to refer to the file ``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with ``'/static/downloads/polls_20101022.tar.gz'`` in your templates. @@ -153,14 +116,14 @@ Management Commands .. highlight:: console -``django.contrib.staticfiles`` exposes two management commands. +``django.contrib.staticfiles`` exposes three management commands. collectstatic ------------- .. django-admin:: collectstatic -Collects the static files into :setting:`STATICFILES_ROOT`. +Collects the static files into :setting:`STATIC_ROOT`. Duplicate file names are by default resolved in a similar way to how template resolution works: the file that is first found in one of the specified @@ -218,44 +181,76 @@ for each relative path, use the ``--first`` option:: This is a debugging aid; it'll show you exactly which static file will be collected for a given path. +runserver +--------- + +Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app +is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static +files and the following new options. + +.. django-admin-option:: --nostatic + +Use the ``--nostatic`` option to disable serving of static files with the +:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is +only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is +in your project's :setting:`INSTALLED_APPS` setting. + +Example usage:: + + django-admin.py runserver --nostatic + +.. django-admin-option:: --insecure + +Use the ``--insecure`` option to force serving of static files with the +:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG` +setting is ``False``. By using this you acknowledge the fact that it's +**grossly inefficient** and probably **insecure**. This is only intended for +local development, should **never be used in production** and is only +available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is +in your project's :setting:`INSTALLED_APPS` setting. + +Example usage:: + + django-admin.py runserver --insecure + .. currentmodule:: None Other Helpers ============= -The ``staticfiles`` context processor -------------------------------------- +The ``static`` context processor +-------------------------------- -.. function:: django.contrib.staticfiles.context_processors.staticfiles +.. function:: django.core.context_processors.static -This context processor adds the :setting:`STATICFILES_URL` into each template -context as the variable ``{{ STATICFILES_URL }}``. To use it, make sure that -``'django.contrib.staticfiles.context_processors.staticfiles'`` appears -somewhere in your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. +This context processor adds the :setting:`STATIC_URL` into each template +context as the variable ``{{ STATIC_URL }}``. To use it, make sure that +``'django.core.context_processors.static'`` appears somewhere in your +:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. Remember, only templates rendered with :class:`~django.template.RequestContext` will have acces to the data provided by this (and any) context processor. -.. templatetag:: get_staticfiles_prefix +.. templatetag:: get_static_prefix -The ``get_staticfiles_prefix`` templatetag -========================================== +The ``get_static_prefix`` templatetag +===================================== .. highlight:: html+django If you're not using :class:`~django.template.RequestContext`, or if you need -more control over exactly where and how :setting:`STATICFILES_URL` is injected -into the template, you can use the :ttag:`get_staticfiles_prefix` template tag +more control over exactly where and how :setting:`STATIC_URL` is injected +into the template, you can use the :ttag:`get_static_prefix` template tag instead:: - {% load staticfiles %} - <img src="{% get_staticfiles_prefix %}images/hi.jpg" /> + {% load static %} + <img src="{% get_static_prefix %}images/hi.jpg" /> There's also a second form you can use to avoid extra processing if you need the value multiple times:: - {% load staticfiles %} - {% get_staticfiles_prefix as STATIC_PREFIX %} + {% load static %} + {% get_static_prefix as STATIC_PREFIX %} <img src="{{ STATIC_PREFIX }}images/hi.jpg" /> <img src="{{ STATIC_PREFIX }}images/hi2.jpg" /> @@ -292,7 +287,7 @@ primary URL configuration:: ) Note, the begin of the pattern (``r'^static/'``) should be your -:setting:`STATICFILES_URL` setting. +:setting:`STATIC_URL` setting. Since this is a bit finicky, there's also a helper function that'll do this for you: @@ -307,3 +302,8 @@ already defined pattern list. Use it like this:: urlpatterns += staticfiles_urlpatterns() +.. warning:: + + 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/``. diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 43e55acab2..ea49e2372d 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -681,35 +681,6 @@ Example usage:: django-admin.py runserver --noreload -.. django-admin-option:: --nostatic - -Use the ``--nostatic`` option to disable serving of static files with the -:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is -only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is -in your project's :setting:`INSTALLED_APPS` setting. - -Example usage:: - - django-admin.py runserver --nostatic - -.. django-admin-option:: --insecure - -Use the ``--insecure`` option to force serving of static files with the -:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG` -setting is ``False``. By using this you acknowledge the fact that it's -**grossly inefficient** and probably **insecure**. This is only intended for -local development, should **never be used in production** and is only -available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is -in your project's :setting:`INSTALLED_APPS` setting. - -See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` -for more details and learn how to :doc:`manage and deploy static files -</howto/static-files>` correctly. - -Example usage:: - - django-admin.py runserver --insecure - Examples of using different ports and addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 95e6861bb6..7f4157c363 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -53,10 +53,10 @@ Default: ``'/static/admin/'`` The URL prefix for admin media -- CSS, JavaScript and images used by the Django administrative interface. Make sure to use a trailing slash, and to have this be -different from the :setting:``MEDIA_URL`` setting (since the same URL cannot be +different from the :setting:`MEDIA_URL` setting (since the same URL cannot be mapped onto two different sets of files). For integration with :doc:`staticfiles </ref/contrib/staticfiles>`, this should be the same as -:setting:`STATICFILES_URL` followed by ``'admin/'``. +:setting:`STATIC_URL` followed by ``'admin/'``. .. setting:: ADMINS @@ -1122,12 +1122,12 @@ Default: ``''`` (Empty string) URL that handles the media served from :setting:`MEDIA_ROOT`, used for :doc:`managing stored files </topics/files>`. -Example: ``"http://media.lawrence.com"`` +Example: ``"http://media.lawrence.com/"`` Note that this should have a trailing slash if it has a path component. - * Good: ``"http://www.example.com/static/"`` - * Bad: ``"http://www.example.com/static"`` + * Good: ``"http://www.example.com/media/"`` + * Bad: ``"http://www.example.com/media"`` MESSAGE_LEVEL ------------- @@ -1486,6 +1486,49 @@ See :doc:`/ref/contrib/sites`. .. _site framework docs: ../sites/ +.. setting:: STATIC_ROOT + +STATIC_ROOT +----------- + +Default: ``''`` (Empty string) + +The absolute path to the directory that contains static content. + +Example: ``"/home/example.com/static/"`` + +When using the :djadmin:`collectstatic` management command of the optional, +:doc:`staticfiles</ref/contrib/staticfiles>` app this will be used to collect +static files into and served from :setting:`STATIC_URL`. + +In that case this is a **required setting**, unless you've overridden +:setting:`STATICFILES_STORAGE` and are using a custom storage backend. + +This is not a place to store your static files permanently under version +control; you should do that in directories that will be found by your +:setting:`STATICFILES_FINDERS` (by default, per-app ``static/`` subdirectories, +and any directories you include in :setting:`STATICFILES_DIRS`). Files from +those locations will be collected into :setting:`STATIC_ROOT`. + +See :doc:`/ref/contrib/staticfiles` and :setting:`STATIC_URL`. + +.. setting:: STATIC_URL + +STATIC_URL +---------- + +Default: ``None`` + +URL that handles the files served from :setting:`STATIC_ROOT`. + +Example: ``"/site_media/static/"`` or ``"http://static.example.com/"`` + +If not ``None``, this will be used as the base path for +:ref:`media definitions<form-media-paths>` and the +:doc:`staticfiles app</ref/contrib/staticfiles>`. + +See :setting:`STATIC_ROOT`. + .. setting:: TEMPLATE_CONTEXT_PROCESSORS TEMPLATE_CONTEXT_PROCESSORS @@ -1496,7 +1539,8 @@ Default:: ("django.contrib.auth.context_processors.auth", "django.core.context_processors.debug", "django.core.context_processors.i18n", - "django.contrib.staticfiles.context_processors.staticfiles", + "django.core.context_processors.media", + "django.core.context_processors.static", "django.contrib.messages.context_processors.messages") A tuple of callables that are used to populate the context in ``RequestContext``. @@ -1513,6 +1557,10 @@ of items to be merged into the context. ``django.core.context_processors.auth`` to ``django.contrib.auth.context_processors.auth``. +.. versionadded:: 1.3 + The ``django.core.context_processors.static`` context processor + was added in this release. + .. setting:: TEMPLATE_DEBUG TEMPLATE_DEBUG diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index aa4951eebe..e02debe39b 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -312,8 +312,8 @@ and return a dictionary of items to be merged into the context. By default, "django.core.context_processors.debug", "django.core.context_processors.i18n", "django.core.context_processors.media", - "django.contrib.messages.context_processors.messages", - "django.contrib.staticfiles.context_processors.staticfiles") + "django.core.context_processors.static", + "django.contrib.messages.context_processors.messages") .. versionadded:: 1.2 In addition to these, ``RequestContext`` always uses @@ -435,6 +435,15 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every ``RequestContext`` will contain a variable ``MEDIA_URL``, providing the value of the :setting:`MEDIA_URL` setting. +django.core.context_processors.static +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.3 + +If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every +``RequestContext`` will contain a variable ``STATIC_URL``, providing the +value of the :setting:`STATIC_URL` setting. + django.core.context_processors.csrf ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index 596d1c7c2b..d6610d1c0e 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/docs/releases/1.3-alpha-1.txt @@ -21,7 +21,7 @@ changes`_ and an easy upgrade path from Django 1.2. .. _new features: `What's new in Django 1.3 alpha 1`_ -.. _backwards incompatible changes: backwards-incompatible-changes-1.3_ +.. _backwards incompatible changes: backwards-incompatible-changes-1.3-alpha-1_ What's new in Django 1.3 alpha 1 ================================ @@ -161,7 +161,7 @@ requests. These include: easier to test the database activity associated with a view. -.. _backwards-incompatible-changes-1.3: +.. _backwards-incompatible-changes-1.3-alpha-1: Backwards-incompatible changes in 1.3 alpha 1 ============================================= @@ -270,8 +270,6 @@ local flavors: official designation "Aceh (ACE)". -.. _deprecated-features-1.3: - Features deprecated in 1.3 ========================== diff --git a/docs/releases/1.3-alpha-2.txt b/docs/releases/1.3-alpha-2.txt index 8a9bdcaa88..c8671a618c 100644 --- a/docs/releases/1.3-alpha-2.txt +++ b/docs/releases/1.3-alpha-2.txt @@ -13,10 +13,6 @@ prior to the final 1.3 release. As such, this release is *not* intended for production use, and any such use is discouraged. -.. _new features: `What's new in Django 1.3 alpha 2`_ - -.. _backwards incompatible changes: backwards-incompatible-changes-1.3-alpha-2_ - What's new in Django 1.3 alpha 2 ================================ @@ -43,6 +39,47 @@ See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` for more details or learn how to :doc:`manage static files </howto/static-files>`. +Backwards-incompatible changes in 1.3 alpha 2 +============================================= + +Introduction of STATIC_URL and STATIC_ROOT settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The newly introduced :doc:`/ref/contrib/staticfiles` app extends Django's +abilities to handle static app and project files, required the additon of +settings to refer to those files in templates and code, especially in +contrast to the :setting:`MEDIA_URL` and :setting:`MEDIA_ROOT` settings that +refer to user-uploaded files. + +Prior to 1.3 alpha 2 these settings were called ``STATICFILES_URL`` and +``STATICFILES_ROOT`` to follow the naming scheme for app centric settings. +Based on feedback from the community it became apparent that those settings +created confusion, especially given the fact handling static files is also +desired outside the use of the optional ``staticfiles`` app. + +As a result, we take the followig steps to rectify the issue: + + * Two new global settings that will be used by -- **but are not limited + to** -- the :doc:`staticfiles</ref/contrib/staticfiles>` app: + + * :setting:`STATIC_ROOT` (formally ``STATICFILES_ROOT``) + + * :setting:`STATIC_URL` (formally ``STATICFILES_URL``) + + * Moving the + ``django.contrib.staticfiles.templatetags.staticfiles.get_staticfiles_prefix`` + template tag to the core (``django.templatetags.static``) and renaming + it to :ttag:`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 + :func:`~django.core.context_processors.static`. + + * :ref:`form-media-paths` will use :setting:`STATIC_URL` as the prefix + **if the value is not None**, and falls back to the previously used + :setting:`MEDIA_URL`. + The Django 1.3 roadmap ====================== diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 553fcc5793..20c98f29c4 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -59,7 +59,7 @@ In previous versions of Django, it was common to place static assets in app is to make it easier to keep static files separate from user-uploaded files. For this reason, you will probably want to make your :setting:`MEDIA_ROOT` and :setting:`MEDIA_URL` different from your -:setting:`STATICFILES_ROOT` and :setting:`STATICFILES_URL`. You will need to +: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 media at all. diff --git a/docs/releases/index.txt b/docs/releases/index.txt index 11d6933706..e2ec6eb062 100644 --- a/docs/releases/index.txt +++ b/docs/releases/index.txt @@ -64,6 +64,7 @@ notes. .. toctree:: :maxdepth: 1 + 1.3-alpha-2 1.3-alpha-1 1.2-rc-1 1.2-beta-1 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 ------------- |