Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Clarified the messages documentation.

* Stated upfront that the messages framework is enabled by default.
* Explained why FallbackStorage, despites its unattractive name, is the
  default and likely the most efficient message storage class.

Thanks Jeremy Dunck for the review.

Closes #17026 (again).
  • Loading branch information...
commit ce53a1d0bf51f59118569ec81e1a30b013bd352e 1 parent fa8fb2b
Aymeric Augustin authored September 07, 2012

Showing 1 changed file with 47 additions and 49 deletions. Show diff stats Hide diff stats

  1. 96  docs/ref/contrib/messages.txt
96  docs/ref/contrib/messages.txt
@@ -5,14 +5,16 @@ The messages framework
5 5
 .. module:: django.contrib.messages
6 6
    :synopsis: Provides cookie- and session-based temporary message storage.
7 7
 
8  
-Quite commonly in web applications, you may need to display a one-time
9  
-notification message (also know as "flash message") to the user after
10  
-processing a form or some other types of user input. For this, Django provides
11  
-full support for cookie- and session-based messaging, for both anonymous and
12  
-authenticated users. The messages framework allows you to temporarily store
13  
-messages in one request and retrieve them for display in a subsequent request
14  
-(usually the next one). Every message is tagged with a specific ``level`` that
15  
-determines its priority (e.g., ``info``, ``warning``, or ``error``).
  8
+Quite commonly in web applications, you need to display a one-time
  9
+notification message (also known as "flash message") to the user after
  10
+processing a form or some other types of user input.
  11
+
  12
+For this, Django provides full support for cookie- and session-based
  13
+messaging, for both anonymous and authenticated users. The messages framework
  14
+allows you to temporarily store messages in one request and retrieve them for
  15
+display in a subsequent request (usually the next one). Every message is
  16
+tagged with a specific ``level`` that determines its priority (e.g., ``info``,
  17
+``warning``, or ``error``).
16 18
 
17 19
 Enabling messages
18 20
 =================
@@ -20,32 +22,27 @@ Enabling messages
20 22
 Messages are implemented through a :doc:`middleware </ref/middleware>`
21 23
 class and corresponding :doc:`context processor </ref/templates/api>`.
22 24
 
23  
-To enable message functionality, do the following:
24  
-
25  
-* Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
26  
-  it contains ``'django.contrib.messages.middleware.MessageMiddleware'``.
  25
+The default ``settings.py`` created by ``django-admin.py startproject``
  26
+already contains all the settings required to enable message functionality:
27 27
 
28  
-  If you are using a :ref:`storage backend <message-storage-backends>` that
29  
-  relies on :doc:`sessions </topics/http/sessions>` (the default),
30  
-  ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be
31  
-  enabled and appear before ``MessageMiddleware`` in your
32  
-  :setting:`MIDDLEWARE_CLASSES`.
  28
+* ``'django.contrib.messages'`` is in :setting:`INSTALLED_APPS`.
33 29
 
34  
-* Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure
35  
-  it contains ``'django.contrib.messages.context_processors.messages'``.
  30
+* :setting:`MIDDLEWARE_CLASSES` contains
  31
+  ``'django.contrib.sessions.middleware.SessionMiddleware'`` and
  32
+  ``'django.contrib.messages.middleware.MessageMiddleware'``.
36 33
 
37  
-* Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS`
38  
-  setting
  34
+  The default :ref:`storage backend <message-storage-backends>` relies on
  35
+  :doc:`sessions </topics/http/sessions>`. That's why ``SessionMiddleware``
  36
+  must be enabled and appear before ``MessageMiddleware`` in
  37
+  :setting:`MIDDLEWARE_CLASSES`.
39 38
 
40  
-The default ``settings.py`` created by ``django-admin.py startproject`` has
41  
-``MessageMiddleware`` activated and the ``django.contrib.messages`` app
42  
-installed. Also, the default value for :setting:`TEMPLATE_CONTEXT_PROCESSORS`
43  
-contains ``'django.contrib.messages.context_processors.messages'``.
  39
+* :setting:`TEMPLATE_CONTEXT_PROCESSORS`   contains
  40
+  ``'django.contrib.messages.context_processors.messages'``.
44 41
 
45  
-If you don't want to use messages, you can remove the
46  
-``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, the ``messages``
47  
-context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
48  
-``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`.
  42
+If you don't want to use messages, you can remove
  43
+``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`, the
  44
+``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, and the
  45
+``messages`` context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS`.
49 46
 
50 47
 Configuring the message engine
51 48
 ==============================
@@ -56,34 +53,35 @@ Storage backends
56 53
 ----------------
57 54
 
58 55
 The messages framework can use different backends to store temporary messages.
59  
-If the default FallbackStorage isn't suitable to your needs, you can change
60  
-which backend is being used by adding a `MESSAGE_STORAGE`_ to your
61  
-settings, referencing the module and class of the storage class. For
62  
-example::
63 56
 
64  
-    MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
  57
+Django provides three built-in storage classes:
65 58
 
66  
-The value should be the full path of the desired storage class.
  59
+.. class:: django.contrib.messages.storage.session.SessionStorage
67 60
 
68  
-Three storage classes are available:
  61
+    This class stores all messages inside of the request's session. Therefore
  62
+    it requires Django's ``contrib.sessions`` application.
69 63
 
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.
  64
+.. class:: django.contrib.messages.storage.cookie.CookieStorage
73 65
 
74  
-``'django.contrib.messages.storage.cookie.CookieStorage'``
75 66
     This class stores the message data in a cookie (signed with a secret hash
76 67
     to prevent manipulation) to persist notifications across requests. Old
77  
-    messages are dropped if the cookie data size would exceed 4096 bytes.
  68
+    messages are dropped if the cookie data size would exceed 2048 bytes.
  69
+
  70
+.. class:: django.contrib.messages.storage.fallback.FallbackStorage
78 71
 
79  
-``'django.contrib.messages.storage.fallback.FallbackStorage'``
80  
-    This is the default storage class.
  72
+    This class first uses ``CookieStorage``, and falls back to using
  73
+    ``SessionStorage`` for the messages that could not fit in a single cookie.
  74
+    It also requires Django's ``contrib.sessions`` application.
81 75
 
82  
-    This class first uses CookieStorage for all messages, falling back to using
83  
-    SessionStorage for the messages that could not fit in a single cookie.
  76
+    This behavior avoids writing to the session whenever possible. It should
  77
+    provide the best performance in the general case.
84 78
 
85  
-    Since it is uses SessionStorage, it also requires Django's
86  
-    ``contrib.sessions`` application.
  79
+:class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the
  80
+default storage class. If it isn't suitable to your needs, you can select
  81
+another storage class by setting `MESSAGE_STORAGE`_ to its full import path,
  82
+for example::
  83
+
  84
+    MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
87 85
 
88 86
 To write your own storage class, subclass the ``BaseStorage`` class in
89 87
 ``django.contrib.messages.storage.base`` and implement the ``_get`` and
@@ -97,8 +95,8 @@ to that of the Python logging module. Message levels allow you to group
97 95
 messages by type so they can be filtered or displayed differently in views and
98 96
 templates.
99 97
 
100  
-The built-in levels (which can be imported from ``django.contrib.messages``
101  
-directly) are:
  98
+The built-in levels, which can be imported from ``django.contrib.messages``
  99
+directly, are:
102 100
 
103 101
 =========== ========
104 102
 Constant    Purpose

0 notes on commit ce53a1d

Please sign in to comment.
Something went wrong with that request. Please try again.