mirror of
https://github.com/django/django.git
synced 2024-12-23 17:46:27 +00:00
c56beed240
Thanks Chris Beaven. git-svn-id: http://code.djangoproject.com/svn/django/trunk@12207 bcc190cf-cafb-0310-a4f2-bffc1f526a37
414 lines
15 KiB
Plaintext
414 lines
15 KiB
Plaintext
.. _ref-contrib-messages:
|
|
|
|
======================
|
|
The messages framework
|
|
======================
|
|
|
|
.. module:: django.contrib.messages
|
|
:synopsis: Provides cookie- and session-based temporary message storage.
|
|
|
|
Django provides full support for cookie- and session-based messaging, for
|
|
both anonymous and authenticated clients. The messages framework allows you
|
|
to temporarily store messages in one request and retrieve them for display
|
|
in a subsequent request (usually the next one). Every message is tagged
|
|
with a specific ``level`` that determines its priority (e.g., ``info``,
|
|
``warning``, or ``error``).
|
|
|
|
.. versionadded:: 1.2
|
|
The messages framework was added.
|
|
|
|
Enabling messages
|
|
=================
|
|
|
|
Messages are implemented through a :ref:`middleware <ref-middleware>`
|
|
class and corresponding :ref:`context processor <ref-templates-api>`.
|
|
|
|
To enable message functionality, do the following:
|
|
|
|
* Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
|
|
it contains ``'django.contrib.messages.middleware.MessageMiddleware'``.
|
|
|
|
If you are using a :ref:`storage backend <message-storage-backends>` that
|
|
relies on :ref:`sessions <topics-http-sessions>` (the default),
|
|
``'django.contrib.sessions.middleware.SessionMiddleware'`` must be
|
|
enabled and appear before ``MessageMiddleware`` in your
|
|
:setting:`MIDDLEWARE_CLASSES`.
|
|
|
|
* Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure
|
|
it contains ``'django.contrib.messages.context_processors.messages'``.
|
|
|
|
* Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS`
|
|
setting
|
|
|
|
The default ``settings.py`` created by ``django-admin.py startproject`` has
|
|
``MessageMiddleware`` activated and the ``django.contrib.messages`` app
|
|
installed. Also, the default value for :setting:`TEMPLATE_CONTEXT_PROCESSORS`
|
|
contains ``'django.contrib.messages.context_processors.messages'``.
|
|
|
|
If you don't want to use messages, you can remove the
|
|
``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, the ``messages``
|
|
context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
|
|
``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`.
|
|
|
|
Configuring the message engine
|
|
==============================
|
|
|
|
.. _message-storage-backends:
|
|
|
|
Storage backends
|
|
----------------
|
|
|
|
The messages framework can use different backends to store temporary messages.
|
|
To change which backend is being used, add a `MESSAGE_STORAGE`_ to your
|
|
settings, referencing the module and class of the storage class. For
|
|
example::
|
|
|
|
MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
|
|
|
|
The value should be the full path of the desired storage class.
|
|
|
|
Four storage classes are included:
|
|
|
|
``'django.contrib.messages.storage.session.SessionStorage'``
|
|
This class stores all messages inside of the request's session. It
|
|
requires Django's ``contrib.sessions`` application.
|
|
|
|
``'django.contrib.messages.storage.cookie.CookieStorage'``
|
|
This class stores the message data in a cookie (signed with a secret hash
|
|
to prevent manipulation) to persist notifications across requests. Old
|
|
messages are dropped if the cookie data size would exceed 4096 bytes.
|
|
|
|
``'django.contrib.messages.storage.fallback.FallbackStorage'``
|
|
This class first uses CookieStorage for all messages, falling back to using
|
|
SessionStorage for the messages that could not fit in a single cookie.
|
|
|
|
Since it is uses SessionStorage, it also requires Django's
|
|
``contrib.session`` application.
|
|
|
|
``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
|
|
This is the default temporary storage class.
|
|
|
|
This class extends FallbackStorage and adds compatibility methods to
|
|
to retrieve any messages stored in the user Message model by code that
|
|
has not yet been updated to use the new API. This storage is temporary
|
|
(because it makes use of code that is pending deprecation) and will be
|
|
removed in Django 1.4. At that time, the default storage will become
|
|
``django.contrib.messages.storage.fallback.FallbackStorage``. For more
|
|
information, see `LegacyFallbackStorage`_ below.
|
|
|
|
To write your own storage class, subclass the ``BaseStorage`` class in
|
|
``django.contrib.messages.storage.base`` and implement the ``_get`` and
|
|
``_store`` methods.
|
|
|
|
LegacyFallbackStorage
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The ``LegacyFallbackStorage`` is a temporary tool to facilitate the transition
|
|
from the deprecated ``user.message_set`` API and will be removed in Django 1.4
|
|
according to Django's standard deprecation policy. For more information, see
|
|
the full :ref:`release process documentation <internals-release-process>`.
|
|
|
|
In addition to the functionality in the ``FallbackStorage``, it adds a custom,
|
|
read-only storage class that retrieves messages from the user ``Message``
|
|
model. Any messages that were stored in the ``Message`` model (e.g., by code
|
|
that has not yet been updated to use the messages framework) will be retrieved
|
|
first, followed by those stored in a cookie and in the session, if any. Since
|
|
messages stored in the ``Message`` model do not have a concept of levels, they
|
|
will be assigned the ``INFO`` level by default.
|
|
|
|
Message levels
|
|
--------------
|
|
|
|
The messages framework is based on a configurable level architecture similar
|
|
to that of the Python logging module. Message levels allow you to group
|
|
messages by type so they can be filtered or displayed differently in views and
|
|
templates.
|
|
|
|
The built-in levels (which can be imported from ``django.contrib.messages``
|
|
directly) are:
|
|
|
|
=========== ========
|
|
Constant Purpose
|
|
=========== ========
|
|
``DEBUG`` Development-related messages that will be ignored (or removed) in a production deployment
|
|
``INFO`` Informational messages for the user
|
|
``SUCCESS`` An action was successful, e.g. "Your profile was updated successfully"
|
|
``WARNING`` A failure did not occur but may be imminent
|
|
``ERROR`` An action was **not** successful or some other failure occurred
|
|
=========== ========
|
|
|
|
The `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.
|
|
|
|
.. _`changed per request`: `Changing the minimum recorded level per-request`_
|
|
|
|
Message tags
|
|
------------
|
|
|
|
Message tags are a string representation of the message level plus any
|
|
extra tags that were added directly in the view (see
|
|
`Adding extra message tags`_ below for more details). Tags are stored in a
|
|
string and are separated by spaces. Typically, message tags
|
|
are used as CSS classes to customize message style based on message type. By
|
|
default, each level has a single tag that's a lowercase version of its own
|
|
constant:
|
|
|
|
============== ===========
|
|
Level Constant Tag
|
|
============== ===========
|
|
``DEBUG`` ``debug``
|
|
``INFO`` ``info``
|
|
``SUCCESS`` ``success``
|
|
``WARNING`` ``warning``
|
|
``ERROR`` ``error``
|
|
============== ===========
|
|
|
|
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
|
|
you wish to change. As this extends the default tags, you only need to provide
|
|
tags for the levels you wish to override::
|
|
|
|
from django.contrib.messages import constants as messages
|
|
MESSAGE_TAGS = {
|
|
messages.INFO: '',
|
|
50: 'critical',
|
|
}
|
|
|
|
Using messages in views and templates
|
|
=====================================
|
|
|
|
Adding a message
|
|
----------------
|
|
|
|
To add a message, call::
|
|
|
|
from django.contrib import messages
|
|
messages.add_message(request, messages.INFO, 'Hello world.')
|
|
|
|
Some shortcut methods provide a standard way to add messages with commonly
|
|
used tags (which are usually represented as HTML classes for the message)::
|
|
|
|
messages.debug(request, '%s SQL statements were executed.' % count)
|
|
messages.info(request, 'Three credits remain in your account.')
|
|
messages.success(request, 'Profile details updated.')
|
|
messages.warning(request, 'Your account expires in three days.')
|
|
messages.error(request, 'Document deleted.')
|
|
|
|
Displaying messages
|
|
-------------------
|
|
|
|
In your template, use something like::
|
|
|
|
{% if messages %}
|
|
<ul class="messages">
|
|
{% for message in messages %}
|
|
<li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
{% endif %}
|
|
|
|
If you're using the context processor, your template should be rendered with a
|
|
``RequestContext``. Otherwise, ensure ``messages`` is available to
|
|
the template context.
|
|
|
|
Creating custom message levels
|
|
------------------------------
|
|
|
|
Messages levels are nothing more than integers, so you can define your own
|
|
level constants and use them to create more customized user feedback, e.g.::
|
|
|
|
CRITICAL = 50
|
|
|
|
def my_view(request):
|
|
messages.add_message(request, CRITICAL, 'A serious error occurred.')
|
|
|
|
When creating custom message levels you should be careful to avoid overloading
|
|
existing levels. The values for the built-in levels are:
|
|
|
|
.. _message-level-constants:
|
|
|
|
============== =====
|
|
Level Constant Value
|
|
============== =====
|
|
``DEBUG`` 10
|
|
``INFO`` 20
|
|
``SUCCESS`` 25
|
|
``WARNING`` 30
|
|
``ERROR`` 40
|
|
============== =====
|
|
|
|
If you need to identify the custom levels in your HTML or CSS, you need to
|
|
provide a mapping via the `MESSAGE_TAGS`_ setting.
|
|
|
|
.. note::
|
|
If you are creating a reusable application, it is recommended to use
|
|
only the built-in `message levels`_ and not rely on any custom levels.
|
|
|
|
Changing the minimum recorded level per-request
|
|
-----------------------------------------------
|
|
|
|
The minimum recorded level can be set per request via the ``set_level``
|
|
method::
|
|
|
|
from django.contrib import messages
|
|
|
|
# Change the messages level to ensure the debug message is added.
|
|
messages.set_level(request, messages.DEBUG)
|
|
messages.debug(request, 'Test message...')
|
|
|
|
# In another request, record only messages with a level of WARNING and higher
|
|
messages.set_level(request, messages.WARNING)
|
|
messages.success(request, 'Your profile was updated.') # ignored
|
|
messages.warning(request, 'Your account is about to expire.') # recorded
|
|
|
|
# Set the messages level back to default.
|
|
messages.set_level(request, None)
|
|
|
|
Similarly, the current effective level can be retrieved with ``get_level``::
|
|
|
|
from django.contrib import messages
|
|
current_level = messages.get_level(request)
|
|
|
|
For more information on how the minimum recorded level functions, see
|
|
`Message levels`_ above.
|
|
|
|
Adding extra message tags
|
|
-------------------------
|
|
|
|
For more direct control over message tags, you can optionally provide a string
|
|
containing extra tags to any of the add methods::
|
|
|
|
messages.add_message(request, messages.INFO, 'Over 9000!',
|
|
extra_tags='dragonball')
|
|
messages.error(request, 'Email box full', extra_tags='email')
|
|
|
|
Extra tags are added before the default tag for that level and are space
|
|
separated.
|
|
|
|
Failing silently when the message framework is disabled
|
|
-------------------------------------------------------
|
|
|
|
If you're writing a reusable app (or other piece of code) and want to include
|
|
messaging functionality, but don't want to require your users to enable it
|
|
if they don't want to, you may pass an additional keyword argument
|
|
``fail_silently=True`` to any of the ``add_message`` family of methods. For
|
|
example::
|
|
|
|
messages.add_message(request, messages.SUCCESS, 'Profile details updated.',
|
|
fail_silently=True)
|
|
messages.info(request, 'Hello world.', fail_silently=True)
|
|
|
|
Internally, Django uses this functionality in the create, update, and delete
|
|
:ref:`generic views <topics-generic-views>` so that they work even if the
|
|
message framework is disabled.
|
|
|
|
.. note::
|
|
Setting ``fail_silently=True`` only hides the ``MessageFailure`` that would
|
|
otherwise occur when the messages framework disabled and one attempts to
|
|
use one of the ``add_message`` family of methods. It does not hide failures
|
|
that may occur for other reasons.
|
|
|
|
Expiration of messages
|
|
======================
|
|
|
|
The messages are marked to be cleared when the storage instance is iterated
|
|
(and cleared when the response is processed).
|
|
|
|
To avoid the messages being cleared, you can set the messages storage to
|
|
``False`` after iterating::
|
|
|
|
storage = messages.get_messages(request)
|
|
for message in storage:
|
|
do_something_with(message)
|
|
storage.used = False
|
|
|
|
Behavior of parallel requests
|
|
=============================
|
|
|
|
Due to the way cookies (and hence sessions) work, **the behavior of any
|
|
backends that make use of cookies or sessions is undefined when the same
|
|
client makes multiple requests that set or get messages in parallel**. For
|
|
example, if a client initiates a request that creates a message in one window
|
|
(or tab) and then another that fetches any uniterated messages in another
|
|
window, before the first window redirects, the message may appear in the
|
|
second window instead of the first window where it may be expected.
|
|
|
|
In short, when multiple simultaneous requests from the same client are
|
|
involved, messages are not guaranteed to be delivered to the same window that
|
|
created them nor, in some cases, at all. Note that this is typically not a
|
|
problem in most applications and will become a non-issue in HTML5, where each
|
|
window/tab will have its own browsing context.
|
|
|
|
Settings
|
|
========
|
|
|
|
A few :ref:`Django settings <ref-settings>` 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.user_messages.LegacyFallbackStorage'``
|
|
|
|
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'``
|
|
* ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
|
|
|
|
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>`.
|
|
|
|
.. _Django settings: ../settings/
|