Permalink
Browse files

Fixed #14633 - Organized settings reference docs and added a topical …

…index.

Thanks Gabriel Hurley for the original idea
and adamv for the draft patch.
  • Loading branch information...
timgraham committed Jan 12, 2013
1 parent 0171ba6 commit ba50d3e05bc9a33aef495a5fbca239afe52237b3
@@ -34,7 +34,8 @@ To get started using the ``comments`` app, follow these steps:
#. Use the `comment template tags`_ below to embed comments in your
templates.
You might also want to examine :doc:`/ref/contrib/comments/settings`.
You might also want to examine :ref:`the available settings
<settings-comments>`.
Comment template tags
=====================
@@ -335,14 +336,20 @@ output the CSRF token and cookie.
.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
Configuration
=============
See :ref:`comment settings <settings-comments>`.
More information
================
.. toctree::
:maxdepth: 1
models
settings
signals
custom
forms

This file was deleted.

Oops, something went wrong.
View
@@ -488,60 +488,10 @@ developers of other reusable apps that want the same guarantees also use the
Settings
========
A number of settings can be used to control Django's CSRF behavior.
A number of settings can be used to control Django's CSRF behavior:
CSRF_COOKIE_DOMAIN
------------------
Default: ``None``
The domain to be used when setting the CSRF cookie. This can be useful for
easily allowing cross-subdomain requests to be excluded from the normal cross
site request forgery protection. It should be set to a string such as
``".example.com"`` to allow a POST request from a form on one subdomain to be
accepted by a view served from another subdomain.
Please note that, with or without use of this setting, this CSRF protection
mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
CSRF_COOKIE_NAME
----------------
Default: ``'csrftoken'``
The name of the cookie to use for the CSRF authentication token. This can be
whatever you want.
CSRF_COOKIE_PATH
----------------
Default: ``'/'``
The path set on the CSRF cookie. This should either match the URL path of your
Django installation or be a parent of that path.
This is useful if you have multiple Django instances running under the same
hostname. They can use different cookie paths, and each instance will only see
its own CSRF cookie.
CSRF_COOKIE_SECURE
------------------
Default: ``False``
Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``,
the cookie will be marked as "secure," which means browsers may ensure that the
cookie is only sent under an HTTPS connection.
CSRF_FAILURE_VIEW
-----------------
Default: ``'django.views.csrf.csrf_failure'``
A dotted path to the view function to be used when an incoming request
is rejected by the CSRF protection. The function should have this signature::
def csrf_failure(request, reason="")
where ``reason`` is a short message (intended for developers or logging, not for
end users) indicating the reason the request was rejected.
* :setting:`CSRF_COOKIE_DOMAIN`
* :setting:`CSRF_COOKIE_NAME`
* :setting:`CSRF_COOKIE_PATH`
* :setting:`CSRF_COOKIE_SECURE`
* :setting:`CSRF_FAILURE_VIEW`
@@ -78,15 +78,17 @@ Django provides three built-in storage classes:
:class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the
default storage class. If it isn't suitable to your needs, you can select
another storage class by setting `MESSAGE_STORAGE`_ to its full import path,
for example::
another storage class by setting setting:`MESSAGE_STORAGE` to its full import
path, for example::
MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
To write your own storage class, subclass the ``BaseStorage`` class in
``django.contrib.messages.storage.base`` and implement the ``_get`` and
``_store`` methods.
.. _message-level:
Message levels
--------------
@@ -108,7 +110,7 @@ Constant Purpose
``ERROR`` An action was **not** successful or some other failure occurred
=========== ========
The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level
The :setting:`MESSAGE_LEVEL` setting can be used to change the minimum recorded level
(or it can be `changed per request`_). Attempts to add messages of a level less
than this will be ignored.
@@ -136,7 +138,7 @@ Level Constant Tag
============== ===========
To change the default tags for a message level (either built-in or custom),
set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels
set the :setting:`MESSAGE_TAGS` setting to a dictionary containing the levels
you wish to change. As this extends the default tags, you only need to provide
tags for the levels you wish to override::
@@ -168,6 +170,8 @@ used tags (which are usually represented as HTML classes for the message)::
messages.warning(request, 'Your account expires in three days.')
messages.error(request, 'Document deleted.')
.. _message-displaying:
Displaying messages
-------------------
@@ -216,7 +220,7 @@ Level Constant Value
============== =====
If you need to identify the custom levels in your HTML or CSS, you need to
provide a mapping via the `MESSAGE_TAGS`_ setting.
provide a mapping via the :setting:`MESSAGE_TAGS` setting.
.. note::
If you are creating a reusable application, it is recommended to use
@@ -316,80 +320,10 @@ window/tab will have its own browsing context.
Settings
========
A few :doc:`Django settings </ref/settings>` give you control over message
A few :ref:`settings<settings-messages>` give you control over message
behavior:
MESSAGE_LEVEL
-------------
Default: ``messages.INFO``
This sets the minimum message that will be saved in the message storage. See
`Message levels`_ above for more details.
.. admonition:: Important
If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
the built-in constants, you must import the constants module directly to
avoid the potential for circular imports, e.g.::
from django.contrib.messages import constants as message_constants
MESSAGE_LEVEL = message_constants.DEBUG
If desired, you may specify the numeric values for the constants directly
according to the values in the above :ref:`constants table
<message-level-constants>`.
MESSAGE_STORAGE
---------------
Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
Controls where Django stores message data. Valid values are:
* ``'django.contrib.messages.storage.fallback.FallbackStorage'``
* ``'django.contrib.messages.storage.session.SessionStorage'``
* ``'django.contrib.messages.storage.cookie.CookieStorage'``
See `Storage backends`_ for more details.
MESSAGE_TAGS
------------
Default::
{messages.DEBUG: 'debug',
messages.INFO: 'info',
messages.SUCCESS: 'success',
messages.WARNING: 'warning',
messages.ERROR: 'error',}
This sets the mapping of message level to message tag, which is typically
rendered as a CSS class in HTML. If you specify a value, it will extend
the default. This means you only have to specify those values which you need
to override. See `Displaying messages`_ above for more details.
.. admonition:: Important
If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
the built-in constants, you must import the ``constants`` module directly to
avoid the potential for circular imports, e.g.::
from django.contrib.messages import constants as message_constants
MESSAGE_TAGS = {message_constants.INFO: ''}
If desired, you may specify the numeric values for the constants directly
according to the values in the above :ref:`constants table
<message-level-constants>`.
SESSION_COOKIE_DOMAIN
---------------------
Default: ``None``
The storage backends that use cookies -- ``CookieStorage`` and
``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in
setting their cookies. See the :doc:`settings documentation </ref/settings>`
for more information on how this works and why you might need to set it.
.. _Django settings: ../settings/
* :setting:`MESSAGE_LEVEL`
* :setting:`MESSAGE_STORAGE`
* :setting:`MESSAGE_TAGS`
* :ref:`SESSION_COOKIE_DOMAIN<messages-session_cookie_domain>`
@@ -19,106 +19,14 @@ can easily be served in production.
Settings
========
.. highlight:: python
.. note::
The following settings control the behavior of the staticfiles app.
.. setting:: STATICFILES_DIRS
STATICFILES_DIRS
----------------
Default: ``[]``
This setting defines the additional locations the staticfiles app will traverse
if the ``FileSystemFinder`` finder is enabled, e.g. if you use the
:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
static file serving view.
This should be set to a list or tuple of strings that contain full paths to
your additional files directory(ies) e.g.::
STATICFILES_DIRS = (
"/home/special.polls.com/polls/static",
"/home/polls.com/polls/static",
"/opt/webfiles/common",
)
Prefixes (optional)
"""""""""""""""""""
In case you want to refer to files in one of the locations with an additional
namespace, you can **optionally** provide a prefix as ``(prefix, path)``
tuples, e.g.::
STATICFILES_DIRS = (
# ...
("downloads", "/opt/webfiles/stats"),
)
Example:
Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
:djadmin:`collectstatic` management command would collect the "stats" files
in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
This would allow you to refer to the local file
``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:
.. code-block:: html+django
<a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
.. setting:: STATICFILES_STORAGE
STATICFILES_STORAGE
-------------------
Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
The file storage engine to use when collecting static files with the
:djadmin:`collectstatic` management command.
A ready-to-use instance of the storage backend defined in this setting
can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``.
For an example, see :ref:`staticfiles-from-cdn`.
.. setting:: STATICFILES_FINDERS
STATICFILES_FINDERS
-------------------
Default::
("django.contrib.staticfiles.finders.FileSystemFinder",
"django.contrib.staticfiles.finders.AppDirectoriesFinder")
The list of finder backends that know how to find static files in
various locations.
The default will find files stored in the :setting:`STATICFILES_DIRS` setting
(using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a
``static`` subdirectory of each app (using
``django.contrib.staticfiles.finders.AppDirectoriesFinder``)
One finder is disabled by default:
``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to
your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
setting.
.. note::
When using the ``AppDirectoriesFinder`` finder, make sure your apps
can be found by staticfiles. Simply add the app to the
:setting:`INSTALLED_APPS` setting of your site.
Static file finders are currently considered a private interface, and this
interface is thus undocumented.
See :ref:`staticfiles settings <settings-staticfiles>` for details on the
following settings:
* :setting:`STATIC_ROOT`
* :setting:`STATIC_URL`
* :setting:`STATICFILES_DIRS`
* :setting:`STATICFILES_STORAGE`
* :setting:`STATICFILES_FINDERS`
Management Commands
===================
Oops, something went wrong.

0 comments on commit ba50d3e

Please sign in to comment.