Django2.0手册:The messages framework



Quite commonly in web applications, you need to display a one-time
notification message (also known as “flash message”) to the user after
processing a form or some other types of user input.

For this, Django provides full support for cookie- and session-based
messaging, for both anonymous and authenticated users. 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).

Enabling messages¶

Messages are implemented through a middleware
class and corresponding context processor.

The default settings.py created by django-admin startproject
already contains all the settings required to enable message functionality:

  • 'django.contrib.messages' is in INSTALLED_APPS.

  • MIDDLEWARE contains
    'django.contrib.sessions.middleware.SessionMiddleware' and
    'django.contrib.messages.middleware.MessageMiddleware'.

    The default storage backend relies on
    sessions. That’s why SessionMiddleware
    must be enabled and appear before MessageMiddleware in
    MIDDLEWARE.

  • The 'context_processors' option of the DjangoTemplates backend
    defined in your TEMPLATES setting contains
    'django.contrib.messages.context_processors.messages'.

If you don’t want to use messages, you can remove
'django.contrib.messages' from your INSTALLED_APPS, the
MessageMiddleware line from MIDDLEWARE, and the messages
context processor from TEMPLATES.

Configuring the message engine¶

Storage backends¶

The messages framework can use different backends to store temporary messages.

Django provides three built-in storage classes in
django.contrib.messages:

class storage.session.SessionStorage

This class stores all messages inside of the request’s session. Therefore
it requires Django’s contrib.sessions application.

class 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 2048 bytes.

class storage.fallback.FallbackStorage

This class first uses CookieStorage, and falls back to using
SessionStorage for the messages that could not fit in a single cookie.
It also requires Django’s contrib.sessions application.

This behavior avoids writing to the session whenever possible. It should
provide the best performance in the general case.

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:

MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
class storage.base.BaseStorage

To write your own storage class, subclass the BaseStorage class in
django.contrib.messages.storage.base and implement the _get and
_store methods.

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.

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¶

add_message(request, level, message, extra_tags=”, fail_silently=False)[source]

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¶

get_messages(request)[source]

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.

Even if you know there is only just one message, you should still iterate over
the messages sequence, because otherwise the message storage will not be cleared
for the next request.

The context processor also provides a DEFAULT_MESSAGE_LEVELS variable which
is a mapping of the message level names to their numeric value:

{% if messages %}
<ul class="messages">
    {% for message in messages %}
    <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>
        {% if message.level == DEFAULT_MESSAGE_LEVELS.ERROR %}Important: {% endif %}
        {{ message }}
    </li>
    {% endfor %}
</ul>
{% endif %}

Outside of templates, you can use
get_messages():

from django.contrib.messages import get_messages

storage = get_messages(request)
for message in storage:
    do_something_with_the_message(message)

For instance, you can fetch all the messages to return them in a
JSONResponseMixin instead of a
TemplateResponseMixin.

get_messages() will return an
instance of the configured storage backend.

The Message class¶

class storage.base.Message

When you loop over the list of messages in a template, what you get are
instances of the Message class. It’s quite a simple object, with only a
few attributes:

  • message: The actual text of the message.
  • level: An integer describing the type of the message (see the
    message levels section above).
  • tags: A string combining all the message’s tags (extra_tags and
    level_tag) separated by spaces.
  • extra_tags: A string containing custom tags for this message,
    separated by spaces. It’s empty by default.
  • level_tag: The string representation of the level. By default, it’s
    the lowercase version of the name of the associated constant, but this
    can be changed if you need by using the MESSAGE_TAGS setting.

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:

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)

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.

Adding messages in class-based views¶

class views.SuccessMessageMixin

Adds a success message attribute to
FormView based classes

get_success_message(cleaned_data)

cleaned_data is the cleaned data from the form which is used for
string formatting

Example views.py:

from django.contrib.messages.views import SuccessMessageMixin
from django.views.generic.edit import CreateView
from myapp.models import Author

class AuthorCreate(SuccessMessageMixin, CreateView):
    model = Author
    success_url = '/success/'
    success_message = "%(name)s was created successfully"

The cleaned data from the form is available for string interpolation using
the %(field_name)s syntax. For ModelForms, if you need access to fields
from the saved object override the
get_success_message()
method.

Example views.py for ModelForms:

from django.contrib.messages.views import SuccessMessageMixin
from django.views.generic.edit import CreateView
from myapp.models import ComplicatedModel

class ComplicatedCreate(SuccessMessageMixin, CreateView):
    model = ComplicatedModel
    success_url = '/success/'
    success_message = "%(calculated_field)s was created successfully"

    def get_success_message(self, cleaned_data):
        return self.success_message % dict(
            cleaned_data,
            calculated_field=self.object.calculated_field,
        )

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 settings give you control over message
behavior:

For backends that use cookies, the settings for the cookie are taken from
the session cookie settings: