PageRenderTime 570ms CodeModel.GetById 548ms RepoModel.GetById 1ms app.codeStats 0ms

Plain Text | 421 lines | 311 code | 110 blank | 0 comment | 0 complexity | 77a8741a0064bfccdc61e091e1269868 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ======================
  2. The messages framework
  3. ======================
  4. .. module:: django.contrib.messages
  5. :synopsis: Provides cookie- and session-based temporary message storage.
  6. Django provides full support for cookie- and session-based messaging, for
  7. both anonymous and authenticated clients. The messages framework allows you
  8. to temporarily store messages in one request and retrieve them for display
  9. in a subsequent request (usually the next one). Every message is tagged
  10. with a specific ``level`` that determines its priority (e.g., ``info``,
  11. ``warning``, or ``error``).
  12. .. versionadded:: 1.2
  13. The messages framework was added.
  14. Enabling messages
  15. =================
  16. Messages are implemented through a :doc:`middleware </ref/middleware>`
  17. class and corresponding :doc:`context processor </ref/templates/api>`.
  18. To enable message functionality, do the following:
  19. * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
  20. it contains ``'django.contrib.messages.middleware.MessageMiddleware'``.
  21. If you are using a :ref:`storage backend <message-storage-backends>` that
  22. relies on :doc:`sessions </topics/http/sessions>` (the default),
  23. ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be
  24. enabled and appear before ``MessageMiddleware`` in your
  25. :setting:`MIDDLEWARE_CLASSES`.
  26. * Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure
  27. it contains ``'django.contrib.messages.context_processors.messages'``.
  28. * Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS`
  29. setting
  30. The default ```` created by `` startproject`` has
  31. ``MessageMiddleware`` activated and the ``django.contrib.messages`` app
  32. installed. Also, the default value for :setting:`TEMPLATE_CONTEXT_PROCESSORS`
  33. contains ``'django.contrib.messages.context_processors.messages'``.
  34. If you don't want to use messages, you can remove the
  35. ``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, the ``messages``
  36. context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
  37. ``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`.
  38. Configuring the message engine
  39. ==============================
  40. .. _message-storage-backends:
  41. Storage backends
  42. ----------------
  43. The messages framework can use different backends to store temporary messages.
  44. To change which backend is being used, add a `MESSAGE_STORAGE`_ to your
  45. settings, referencing the module and class of the storage class. For
  46. example::
  48. The value should be the full path of the desired storage class.
  49. Four storage classes are included:
  50. ``''``
  51. This class stores all messages inside of the request's session. It
  52. requires Django's ``contrib.sessions`` application.
  53. ``''``
  54. This class stores the message data in a cookie (signed with a secret hash
  55. to prevent manipulation) to persist notifications across requests. Old
  56. messages are dropped if the cookie data size would exceed 4096 bytes.
  57. ``''``
  58. This class first uses CookieStorage for all messages, falling back to using
  59. SessionStorage for the messages that could not fit in a single cookie.
  60. Since it is uses SessionStorage, it also requires Django's
  61. ``contrib.sessions`` application.
  62. ``''``
  63. This is the default temporary storage class.
  64. This class extends FallbackStorage and adds compatibility methods
  65. to retrieve any messages stored in the user Message model by code that
  66. has not yet been updated to use the new API. This storage is temporary
  67. (because it makes use of code that is pending deprecation) and will be
  68. removed in Django 1.4. At that time, the default storage will become
  69. ````. For more
  70. information, see `LegacyFallbackStorage`_ below.
  71. To write your own storage class, subclass the ``BaseStorage`` class in
  72. ```` and implement the ``_get`` and
  73. ``_store`` methods.
  74. LegacyFallbackStorage
  75. ^^^^^^^^^^^^^^^^^^^^^
  76. The ``LegacyFallbackStorage`` is a temporary tool to facilitate the transition
  77. from the deprecated ``user.message_set`` API and will be removed in Django 1.4
  78. according to Django's standard deprecation policy. For more information, see
  79. the full :doc:`release process documentation </internals/release-process>`.
  80. In addition to the functionality in the ``FallbackStorage``, it adds a custom,
  81. read-only storage class that retrieves messages from the user ``Message``
  82. model. Any messages that were stored in the ``Message`` model (e.g., by code
  83. that has not yet been updated to use the messages framework) will be retrieved
  84. first, followed by those stored in a cookie and in the session, if any. Since
  85. messages stored in the ``Message`` model do not have a concept of levels, they
  86. will be assigned the ``INFO`` level by default.
  87. Message levels
  88. --------------
  89. The messages framework is based on a configurable level architecture similar
  90. to that of the Python logging module. Message levels allow you to group
  91. messages by type so they can be filtered or displayed differently in views and
  92. templates.
  93. The built-in levels (which can be imported from ``django.contrib.messages``
  94. directly) are:
  95. =========== ========
  96. Constant Purpose
  97. =========== ========
  98. ``DEBUG`` Development-related messages that will be ignored (or removed) in a production deployment
  99. ``INFO`` Informational messages for the user
  100. ``SUCCESS`` An action was successful, e.g. "Your profile was updated successfully"
  101. ``WARNING`` A failure did not occur but may be imminent
  102. ``ERROR`` An action was **not** successful or some other failure occurred
  103. =========== ========
  104. The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level
  105. (or it can be `changed per request`_). Attempts to add messages of a level less
  106. than this will be ignored.
  107. .. _`changed per request`: `Changing the minimum recorded level per-request`_
  108. Message tags
  109. ------------
  110. Message tags are a string representation of the message level plus any
  111. extra tags that were added directly in the view (see
  112. `Adding extra message tags`_ below for more details). Tags are stored in a
  113. string and are separated by spaces. Typically, message tags
  114. are used as CSS classes to customize message style based on message type. By
  115. default, each level has a single tag that's a lowercase version of its own
  116. constant:
  117. ============== ===========
  118. Level Constant Tag
  119. ============== ===========
  120. ``DEBUG`` ``debug``
  121. ``INFO`` ``info``
  122. ``SUCCESS`` ``success``
  123. ``WARNING`` ``warning``
  124. ``ERROR`` ``error``
  125. ============== ===========
  126. To change the default tags for a message level (either built-in or custom),
  127. set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels
  128. you wish to change. As this extends the default tags, you only need to provide
  129. tags for the levels you wish to override::
  130. from django.contrib.messages import constants as messages
  131. MESSAGE_TAGS = {
  132. messages.INFO: '',
  133. 50: 'critical',
  134. }
  135. Using messages in views and templates
  136. =====================================
  137. Adding a message
  138. ----------------
  139. To add a message, call::
  140. from django.contrib import messages
  141. messages.add_message(request, messages.INFO, 'Hello world.')
  142. Some shortcut methods provide a standard way to add messages with commonly
  143. used tags (which are usually represented as HTML classes for the message)::
  144. messages.debug(request, '%s SQL statements were executed.' % count)
  145., 'Three credits remain in your account.')
  146. messages.success(request, 'Profile details updated.')
  147. messages.warning(request, 'Your account expires in three days.')
  148. messages.error(request, 'Document deleted.')
  149. Displaying messages
  150. -------------------
  151. In your template, use something like::
  152. {% if messages %}
  153. <ul class="messages">
  154. {% for message in messages %}
  155. <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
  156. {% endfor %}
  157. </ul>
  158. {% endif %}
  159. If you're using the context processor, your template should be rendered with a
  160. ``RequestContext``. Otherwise, ensure ``messages`` is available to
  161. the template context.
  162. Creating custom message levels
  163. ------------------------------
  164. Messages levels are nothing more than integers, so you can define your own
  165. level constants and use them to create more customized user feedback, e.g.::
  166. CRITICAL = 50
  167. def my_view(request):
  168. messages.add_message(request, CRITICAL, 'A serious error occurred.')
  169. When creating custom message levels you should be careful to avoid overloading
  170. existing levels. The values for the built-in levels are:
  171. .. _message-level-constants:
  172. ============== =====
  173. Level Constant Value
  174. ============== =====
  175. ``DEBUG`` 10
  176. ``INFO`` 20
  177. ``SUCCESS`` 25
  178. ``WARNING`` 30
  179. ``ERROR`` 40
  180. ============== =====
  181. If you need to identify the custom levels in your HTML or CSS, you need to
  182. provide a mapping via the `MESSAGE_TAGS`_ setting.
  183. .. note::
  184. If you are creating a reusable application, it is recommended to use
  185. only the built-in `message levels`_ and not rely on any custom levels.
  186. Changing the minimum recorded level per-request
  187. -----------------------------------------------
  188. The minimum recorded level can be set per request via the ``set_level``
  189. method::
  190. from django.contrib import messages
  191. # Change the messages level to ensure the debug message is added.
  192. messages.set_level(request, messages.DEBUG)
  193. messages.debug(request, 'Test message...')
  194. # In another request, record only messages with a level of WARNING and higher
  195. messages.set_level(request, messages.WARNING)
  196. messages.success(request, 'Your profile was updated.') # ignored
  197. messages.warning(request, 'Your account is about to expire.') # recorded
  198. # Set the messages level back to default.
  199. messages.set_level(request, None)
  200. Similarly, the current effective level can be retrieved with ``get_level``::
  201. from django.contrib import messages
  202. current_level = messages.get_level(request)
  203. For more information on how the minimum recorded level functions, see
  204. `Message levels`_ above.
  205. Adding extra message tags
  206. -------------------------
  207. For more direct control over message tags, you can optionally provide a string
  208. containing extra tags to any of the add methods::
  209. messages.add_message(request, messages.INFO, 'Over 9000!',
  210. extra_tags='dragonball')
  211. messages.error(request, 'Email box full', extra_tags='email')
  212. Extra tags are added before the default tag for that level and are space
  213. separated.
  214. Failing silently when the message framework is disabled
  215. -------------------------------------------------------
  216. If you're writing a reusable app (or other piece of code) and want to include
  217. messaging functionality, but don't want to require your users to enable it
  218. if they don't want to, you may pass an additional keyword argument
  219. ``fail_silently=True`` to any of the ``add_message`` family of methods. For
  220. example::
  221. messages.add_message(request, messages.SUCCESS, 'Profile details updated.',
  222. fail_silently=True)
  223., 'Hello world.', fail_silently=True)
  224. Internally, Django uses this functionality in the create, update, and delete
  225. :doc:`generic views </topics/http/generic-views>` so that they work even if the
  226. message framework is disabled.
  227. .. note::
  228. Setting ``fail_silently=True`` only hides the ``MessageFailure`` that would
  229. otherwise occur when the messages framework disabled and one attempts to
  230. use one of the ``add_message`` family of methods. It does not hide failures
  231. that may occur for other reasons.
  232. Expiration of messages
  233. ======================
  234. The messages are marked to be cleared when the storage instance is iterated
  235. (and cleared when the response is processed).
  236. To avoid the messages being cleared, you can set the messages storage to
  237. ``False`` after iterating::
  238. storage = messages.get_messages(request)
  239. for message in storage:
  240. do_something_with(message)
  241. storage.used = False
  242. Behavior of parallel requests
  243. =============================
  244. Due to the way cookies (and hence sessions) work, **the behavior of any
  245. backends that make use of cookies or sessions is undefined when the same
  246. client makes multiple requests that set or get messages in parallel**. For
  247. example, if a client initiates a request that creates a message in one window
  248. (or tab) and then another that fetches any uniterated messages in another
  249. window, before the first window redirects, the message may appear in the
  250. second window instead of the first window where it may be expected.
  251. In short, when multiple simultaneous requests from the same client are
  252. involved, messages are not guaranteed to be delivered to the same window that
  253. created them nor, in some cases, at all. Note that this is typically not a
  254. problem in most applications and will become a non-issue in HTML5, where each
  255. window/tab will have its own browsing context.
  256. Settings
  257. ========
  258. A few :doc:`Django settings </ref/settings>` give you control over message
  259. behavior:
  261. -------------
  262. Default: ``messages.INFO``
  263. This sets the minimum message that will be saved in the message storage. See
  264. `Message levels`_ above for more details.
  265. .. admonition:: Important
  266. If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
  267. the built-in constants, you must import the constants module directly to
  268. avoid the potential for circular imports, e.g.::
  269. from django.contrib.messages import constants as message_constants
  270. MESSAGE_LEVEL = message_constants.DEBUG
  271. If desired, you may specify the numeric values for the constants directly
  272. according to the values in the above :ref:`constants table
  273. <message-level-constants>`.
  275. ---------------
  276. Default: ``''``
  277. Controls where Django stores message data. Valid values are:
  278. * ``''``
  279. * ``''``
  280. * ``''``
  281. * ``''``
  282. See `Storage backends`_ for more details.
  284. ------------
  285. Default::
  286. {messages.DEBUG: 'debug',
  287. messages.INFO: 'info',
  288. messages.SUCCESS: 'success',
  289. messages.WARNING: 'warning',
  290. messages.ERROR: 'error',}
  291. This sets the mapping of message level to message tag, which is typically
  292. rendered as a CSS class in HTML. If you specify a value, it will extend
  293. the default. This means you only have to specify those values which you need
  294. to override. See `Displaying messages`_ above for more details.
  295. .. admonition:: Important
  296. If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
  297. the built-in constants, you must import the ``constants`` module directly to
  298. avoid the potential for circular imports, e.g.::
  299. from django.contrib.messages import constants as message_constants
  300. MESSAGE_TAGS = {message_constants.INFO: ''}
  301. If desired, you may specify the numeric values for the constants directly
  302. according to the values in the above :ref:`constants table
  303. <message-level-constants>`.
  305. ---------------------
  306. Default: ``None``
  307. The storage backends that use cookies -- ``CookieStorage`` and
  308. ``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in
  309. setting their cookies. See the :doc:`settings documentation </ref/settings>`
  310. for more information on how this works and why you might need to set it.
  311. .. _Django settings: ../settings/