← Back to branch summary

~ubuntu-branches/debian/sid/python-django/sid

« back to all changes in this revision

Viewing changes to docs/ref/contrib/messages.txt

  • Committer: Package Import Robot
  • Author(s): Luke Faraone
  • Date: 2013-11-07 15:33:49 UTC
  • mfrom: (1.3.12)
  • Revision ID: package-import@ubuntu.com-20131107153349-e31sc149l2szs3jb
Tags: 1.6-1
http://bugs.debian.org/557474
http://bugs.debian.org/724637
http://bugs.debian.org/636511
http://bugs.debian.org/686333
http://bugs.debian.org/704203
* New upstream version. Closes: #557474, #724637.
* python-django now also suggests the installation of ipython,
  bpython, python-django-doc, and libgdal1.
  Closes: #636511, #686333, #704203
* Set package maintainer to Debian Python Modules Team.
* Bump standards version to 3.9.5, no changes needed.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/contrib/messages.txt
79
79
 
80
80
:class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the
81
81
default storage class. If it isn't suitable to your needs, you can select
82
 
another storage class by setting `MESSAGE_STORAGE`_ to its full import path,
83
 
for example::
 
82
another storage class by setting :setting:`MESSAGE_STORAGE` to its full import
 
83
path, for example::
84
84
 
85
85
    MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
86
86
 
90
90
``django.contrib.messages.storage.base`` and implement the ``_get`` and
91
91
``_store`` methods.
92
92
 
 
93
.. _message-level:
 
94
 
93
95
Message levels
94
96
--------------
95
97
 
111
113
``ERROR``   An action was **not** successful or some other failure occurred
112
114
=========== ========
113
115
 
114
 
The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level
 
116
The :setting:`MESSAGE_LEVEL` setting can be used to change the minimum recorded level
115
117
(or it can be `changed per request`_). Attempts to add messages of a level less
116
118
than this will be ignored.
117
119
 
139
141
==============  ===========
140
142
 
141
143
To change the default tags for a message level (either built-in or custom),
142
 
set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels
 
144
set the :setting:`MESSAGE_TAGS` setting to a dictionary containing the levels
143
145
you wish to change. As this extends the default tags, you only need to provide
144
146
tags for the levels you wish to override::
145
147
 
171
173
    messages.warning(request, 'Your account expires in three days.')
172
174
    messages.error(request, 'Document deleted.')
173
175
 
 
176
.. _message-displaying:
 
177
 
174
178
Displaying messages
175
179
-------------------
176
180
 
219
223
==============  =====
220
224
 
221
225
If you need to identify the custom levels in your HTML or CSS, you need to
222
 
provide a mapping via the `MESSAGE_TAGS`_ setting.
 
226
provide a mapping via the :setting:`MESSAGE_TAGS` setting.
223
227
 
224
228
.. note::
225
229
   If you are creating a reusable application, it is recommended to use
285
289
   use one of the ``add_message`` family of methods. It does not hide failures
286
290
   that may occur for other reasons.
287
291
 
 
292
Adding messages in Class Based Views
 
293
------------------------------------
 
294
 
 
295
.. versionadded:: 1.6
 
296
 
 
297
.. class:: views.SuccessMessageMixin
 
298
 
 
299
    Adds a success message attribute to
 
300
    :class:`~django.views.generic.edit.FormView` based classes
 
301
 
 
302
    .. method:: get_success_message(cleaned_data)
 
303
 
 
304
        ``cleaned_data`` is the cleaned data from the form which is used for
 
305
        string formatting
 
306
 
 
307
**Example views.py**::
 
308
 
 
309
    from django.contrib.messages.views import SuccessMessageMixin
 
310
    from django.views.generic.edit import CreateView
 
311
    from myapp.models import Author
 
312
 
 
313
    class AuthorCreate(SuccessMessageMixin, CreateView):
 
314
        model = Author
 
315
        success_url = '/success/'
 
316
        success_message = "%(name)s was created successfully"
 
317
 
 
318
The cleaned data from the ``form`` is available for string interpolation using
 
319
the ``%(field_name)s`` syntax. For ModelForms, if you need access to fields
 
320
from the saved ``object`` override the
 
321
:meth:`~django.contrib.messages.views.SuccessMessageMixin.get_success_message`
 
322
method.
 
323
 
 
324
**Example views.py for ModelForms**::
 
325
 
 
326
    from django.contrib.messages.views import SuccessMessageMixin
 
327
    from django.views.generic.edit import CreateView
 
328
    from myapp.models import ComplicatedModel
 
329
 
 
330
    class ComplicatedCreate(SuccessMessageMixin, CreateView):
 
331
        model = ComplicatedModel
 
332
        success_url = '/success/'
 
333
        success_message = "%(calculated_field)s was created successfully"
 
334
 
 
335
        def get_success_message(self, cleaned_data):
 
336
            return self.success_message % dict(cleaned_data,
 
337
                                               calculated_field=self.object.calculated_field)
 
338
 
288
339
Expiration of messages
289
340
======================
290
341
 
319
370
Settings
320
371
========
321
372
 
322
 
A few :doc:`Django settings </ref/settings>` give you control over message
 
373
A few :ref:`settings<settings-messages>` give you control over message
323
374
behavior:
324
375
 
325
 
MESSAGE_LEVEL
326
 
-------------
327
 
 
328
 
Default: ``messages.INFO``
329
 
 
330
 
This sets the minimum message that will be saved in the message storage. See
331
 
`Message levels`_ above for more details.
332
 
 
333
 
.. admonition:: Important
334
 
 
335
 
   If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
336
 
   the built-in constants, you must import the constants module directly to
337
 
   avoid the potential for circular imports, e.g.::
338
 
 
339
 
       from django.contrib.messages import constants as message_constants
340
 
       MESSAGE_LEVEL = message_constants.DEBUG
341
 
 
342
 
   If desired, you may specify the numeric values for the constants directly
343
 
   according to the values in the above :ref:`constants table
344
 
   <message-level-constants>`.
345
 
 
346
 
MESSAGE_STORAGE
347
 
---------------
348
 
 
349
 
Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
350
 
 
351
 
Controls where Django stores message data. Valid values are:
352
 
 
353
 
* ``'django.contrib.messages.storage.fallback.FallbackStorage'``
354
 
* ``'django.contrib.messages.storage.session.SessionStorage'``
355
 
* ``'django.contrib.messages.storage.cookie.CookieStorage'``
356
 
 
357
 
See `Storage backends`_ for more details.
358
 
 
359
 
MESSAGE_TAGS
360
 
------------
361
 
 
362
 
Default::
363
 
 
364
 
        {messages.DEBUG: 'debug',
365
 
        messages.INFO: 'info',
366
 
        messages.SUCCESS: 'success',
367
 
        messages.WARNING: 'warning',
368
 
        messages.ERROR: 'error',}
369
 
 
370
 
This sets the mapping of message level to message tag, which is typically
371
 
rendered as a CSS class in HTML. If you specify a value, it will extend
372
 
the default. This means you only have to specify those values which you need
373
 
to override. See `Displaying messages`_ above for more details.
374
 
 
375
 
.. admonition:: Important
376
 
 
377
 
   If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
378
 
   the built-in constants, you must import the ``constants`` module directly to
379
 
   avoid the potential for circular imports, e.g.::
380
 
 
381
 
       from django.contrib.messages import constants as message_constants
382
 
       MESSAGE_TAGS = {message_constants.INFO: ''}
383
 
 
384
 
   If desired, you may specify the numeric values for the constants directly
385
 
   according to the values in the above :ref:`constants table
386
 
   <message-level-constants>`.
387
 
 
388
 
SESSION_COOKIE_DOMAIN
389
 
---------------------
390
 
 
391
 
Default: ``None``
392
 
 
393
 
The storage backends that use cookies -- ``CookieStorage`` and
394
 
``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in
395
 
setting their cookies. See the :doc:`settings documentation </ref/settings>`
396
 
for more information on how this works and why you might need to set it.
397
 
 
398
 
.. _Django settings: ../settings/
 
376
* :setting:`MESSAGE_LEVEL`
 
377
* :setting:`MESSAGE_STORAGE`
 
378
* :setting:`MESSAGE_TAGS`