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

#. 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

=====================

.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)

Configuration

=============

See :ref:`comment settings <settings-comments>`.

More information

================

   :maxdepth: 1

   models

   settings

   signals

   custom

   forms

================

Comment settings

================

These settings configure the behavior of the comments framework:

.. setting:: COMMENTS_HIDE_REMOVED

COMMENTS_HIDE_REMOVED

---------------------

If ``True`` (default), removed comments will be excluded from comment

lists/counts (as taken from template tags). Otherwise, the template author is

responsible for some sort of a "this comment has been removed by the site staff"

message.

.. setting:: COMMENT_MAX_LENGTH

COMMENT_MAX_LENGTH

------------------

The maximum length of the comment field, in characters. Comments longer than

this will be rejected. Defaults to 3000.

.. setting:: COMMENTS_APP

COMMENTS_APP

------------

An app which provides :doc:`customization of the comments framework

</ref/contrib/comments/custom>`.  Use the same dotted-string notation

as in :setting:`INSTALLED_APPS`.  Your custom :setting:`COMMENTS_APP`

must also be listed in :setting:`INSTALLED_APPS`.

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`

: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'

``django.contrib.messages.storage.base`` and implement the ``_get`` and

``_store`` methods.

.. _message-level:

Message levels

--------------

``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.

==============  ===========

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::

    messages.warning(request, 'Your account expires in three days.')

    messages.error(request, 'Document deleted.')

.. _message-displaying:

Displaying messages

-------------------

==============  =====

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

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>`

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

===================