PageRenderTime 11ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 1ms

/docs/ref/contrib/messages.txt

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