Quite commonly in web applications, you need to display a one-time\nnotification message (also known as “flash message”) to the user after\nprocessing a form or some other types of user input.
\nFor this, Django provides full support for cookie- and session-based\nmessaging, for both anonymous and authenticated users. The messages framework\nallows you to temporarily store messages in one request and retrieve them for\ndisplay in a subsequent request (usually the next one). Every message is\ntagged with a specific level that determines its priority (e.g., info,\nwarning, or error).
Messages are implemented through a middleware\nclass and corresponding context processor.
\nThe default settings.py created by django-admin startproject\nalready contains all the settings required to enable message functionality:
'django.contrib.messages' is in INSTALLED_APPS.
MIDDLEWARE contains\n'django.contrib.sessions.middleware.SessionMiddleware' and\n'django.contrib.messages.middleware.MessageMiddleware'.
The default storage backend relies on\nsessions. That’s why SessionMiddleware\nmust be enabled and appear before MessageMiddleware in\nMIDDLEWARE.
The 'context_processors' option of the DjangoTemplates backend\ndefined in your TEMPLATES setting contains\n'django.contrib.messages.context_processors.messages'.
If you don’t want to use messages, you can remove\n'django.contrib.messages' from your INSTALLED_APPS, the\nMessageMiddleware line from MIDDLEWARE, and the messages\ncontext processor from TEMPLATES.
The messages framework can use different backends to store temporary messages.
\nDjango provides three built-in storage classes in\ndjango.contrib.messages:
This class stores all messages inside of the request’s session. Therefore\nit requires Django’s contrib.sessions application.
This class stores the message data in a cookie (signed with a secret hash\nto prevent manipulation) to persist notifications across requests. Old\nmessages are dropped if the cookie data size would exceed 2048 bytes.
\nThis class first uses CookieStorage, and falls back to using\nSessionStorage for the messages that could not fit in a single cookie.\nIt also requires Django’s contrib.sessions application.
This behavior avoids writing to the session whenever possible. It should\nprovide the best performance in the general case.
\nFallbackStorage is the\ndefault storage class. If it isn’t suitable to your needs, you can select\nanother storage class by setting MESSAGE_STORAGE to its full import\npath, for example:
MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"\nTo write your own storage class, subclass the BaseStorage class in\ndjango.contrib.messages.storage.base and implement the _get and\n_store methods.
The messages framework is based on a configurable level architecture similar\nto that of the Python logging module. Message levels allow you to group\nmessages by type so they can be filtered or displayed differently in views and\ntemplates.
\nThe built-in levels, which can be imported from django.contrib.messages\ndirectly, are:
Constant | \nPurpose | \n
|---|---|
| \nDevelopment-related messages that will be ignored (or removed) in a production deployment | \n
| \nInformational messages for the user | \n
| \nAn action was successful, e.g. “Your profile was updated successfully” | \n
| \nA failure did not occur but may be imminent | \n
| \nAn action was not successful or some other failure occurred | \n
The MESSAGE_LEVEL setting can be used to change the minimum recorded\nlevel (or it can be changed per request). Attempts to add messages of a\nlevel less than this will be ignored.
To add a message, call:
\nfrom django.contrib import messages\n\nmessages.add_message(request, messages.INFO, "Hello world.")\nSome shortcut methods provide a standard way to add messages with commonly\nused tags (which are usually represented as HTML classes for the message):
\nmessages.debug(request, "%s SQL statements were executed." % count)\nmessages.info(request, "Three credits remain in your account.")\nmessages.success(request, "Profile details updated.")\nmessages.warning(request, "Your account expires in three days.")\nmessages.error(request, "Document deleted.")\nIn your template, use something like:
\n{% if messages %}\n<ul class="messages">\n {% for message in messages %}\n <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>\n {% endfor %}\n</ul>\n{% endif %}\nIf you’re using the context processor, your template should be rendered with a\nRequestContext. Otherwise, ensure messages is available to\nthe template context.
Even if you know there is only one message, you should still iterate over the\nmessages sequence, because otherwise the message storage will not be\ncleared for the next request.
The context processor also provides a DEFAULT_MESSAGE_LEVELS variable which\nis a mapping of the message level names to their numeric value:
{% if messages %}\n<ul class="messages">\n {% for message in messages %}\n <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>\n {% if message.level == DEFAULT_MESSAGE_LEVELS.ERROR %}Important: {% endif %}\n {{ message }}\n </li>\n {% endfor %}\n</ul>\n{% endif %}\nOutside of templates, you can use\nget_messages():
from django.contrib.messages import get_messages\n\nstorage = get_messages(request)\nfor message in storage:\n do_something_with_the_message(message)\nFor instance, you can fetch all the messages to return them in a\nJSONResponseMixin instead of a\nTemplateResponseMixin.
get_messages() will return an\ninstance of the configured storage backend.
Message classLink to this heading#When you loop over the list of messages in a template, what you get are\ninstances of the Message class. They have only a few attributes:
message: The actual text of the message.
level: An integer describing the type of the message (see the\nmessage levels section above).
tags: A string combining all the message’s tags (extra_tags and\nlevel_tag) separated by spaces.
extra_tags: A string containing custom tags for this message,\nseparated by spaces. It’s empty by default.
level_tag: The string representation of the level. By default, it’s\nthe lowercase version of the name of the associated constant, but this\ncan be changed if you need by using the MESSAGE_TAGS setting.
Messages levels are nothing more than integers, so you can define your own\nlevel constants and use them to create more customized user feedback, e.g.:
\nCRITICAL = 50\n\n\ndef my_view(request):\n messages.add_message(request, CRITICAL, "A serious error occurred.")\nWhen creating custom message levels you should be careful to avoid overloading\nexisting levels. The values for the built-in levels are:
\nLevel Constant | \n값 | \n
|---|---|
| \n10 | \n
| \n20 | \n
| \n25 | \n
| \n30 | \n
| \n40 | \n
If you need to identify the custom levels in your HTML or CSS, you need to\nprovide a mapping via the MESSAGE_TAGS setting.
The minimum recorded level can be set per request via the set_level\nmethod:
from django.contrib import messages\n\n# Change the messages level to ensure the debug message is added.\nmessages.set_level(request, messages.DEBUG)\nmessages.debug(request, "Test message...")\n\n# In another request, record only messages with a level of WARNING and higher\nmessages.set_level(request, messages.WARNING)\nmessages.success(request, "Your profile was updated.") # ignored\nmessages.warning(request, "Your account is about to expire.") # recorded\n\n# Set the messages level back to default.\nmessages.set_level(request, None)\nSimilarly, the current effective level can be retrieved with get_level:
from django.contrib import messages\n\ncurrent_level = messages.get_level(request)\nFor more information on how the minimum recorded level functions, see\nMessage levels above.
\nIf you’re writing a reusable app (or other piece of code) and want to include\nmessaging functionality, but don’t want to require your users to enable it\nif they don’t want to, you may pass an additional keyword argument\nfail_silently=True to any of the add_message family of methods. For\nexample:
messages.add_message(\n request,\n messages.SUCCESS,\n "Profile details updated.",\n fail_silently=True,\n)\nmessages.info(request, "Hello world.", fail_silently=True)\nAdds a success message attribute to\nFormView based classes
cleaned_data is the cleaned data from the form which is used for\nstring formatting
Example views.py:
\nfrom django.contrib.messages.views import SuccessMessageMixin\nfrom django.views.generic.edit import CreateView\nfrom myapp.models import Author\n\n\nclass AuthorCreateView(SuccessMessageMixin, CreateView):\n model = Author\n success_url = "/success/"\n success_message = "%(name)s was created successfully"\nThe cleaned data from the form is available for string interpolation using\nthe %(field_name)s syntax. For ModelForms, if you need access to fields\nfrom the saved object override the\nget_success_message()\nmethod.
Example views.py for ModelForms:
\nfrom django.contrib.messages.views import SuccessMessageMixin\nfrom django.views.generic.edit import CreateView\nfrom myapp.models import ComplicatedModel\n\n\nclass ComplicatedCreateView(SuccessMessageMixin, CreateView):\n model = ComplicatedModel\n success_url = "/success/"\n success_message = "%(calculated_field)s was created successfully"\n\n def get_success_message(self, cleaned_data):\n return self.success_message % dict(\n cleaned_data,\n calculated_field=self.object.calculated_field,\n )\nThe messages are marked to be cleared when the storage instance is iterated\n(and cleared when the response is processed).
\nTo avoid the messages being cleared, you can set the messages storage to\nFalse after iterating:
storage = messages.get_messages(request)\nfor message in storage:\n do_something_with(message)\nstorage.used = False\nDue to the way cookies (and hence sessions) work, the behavior of any\nbackends that make use of cookies or sessions is undefined when the same\nclient makes multiple requests that set or get messages in parallel. For\nexample, if a client initiates a request that creates a message in one window\n(or tab) and then another that fetches any uniterated messages in another\nwindow, before the first window redirects, the message may appear in the\nsecond window instead of the first window where it may be expected.
\nIn short, when multiple simultaneous requests from the same client are\ninvolved, messages are not guaranteed to be delivered to the same window that\ncreated them nor, in some cases, at all. Note that this is typically not a\nproblem in most applications and will become a non-issue in HTML5, where each\nwindow/tab will have its own browsing context.
\nA few settings give you control over message\nbehavior:
\n\nFor backends that use cookies, the settings for the cookie are taken from\nthe session cookie settings:
\n\nThis module offers a tailored test assertion method, for testing messages\nattached to an HttpResponse.
To benefit from this assertion, add MessagesTestMixin to the class\nhierarchy:
from django.contrib.messages.test import MessagesTestMixin\nfrom django.test import TestCase\n\n\nclass MsgTestCase(MessagesTestMixin, TestCase):\n pass\nThen, inherit from the MsgTestCase in your tests.
Asserts that messages added to the response matches expected_messages.
expected_messages is a list of\nMessage objects.
By default, the comparison is ordering dependent. You can disable this by\nsetting the ordered argument to False.