Ticket #4604: visitor_messages.patch

django/contrib/sessions/context_processors.py

@@ +1 @@
+def visitor_messages(request):
+    """
+    Returns any messages in the session's message queue.
+    """
+    return {
+        'visitor_messages': request.session.get_and_delete_messages(),
+    }

django/contrib/sessions/middleware.py

@@ -6 +6 @@
 
 TEST_COOKIE_NAME = 'testcookie'
 TEST_COOKIE_VALUE = 'worked'
+MESSAGES_NAME = '_messages'
 
 class SessionWrapper(object):
     def __init__(self, session_key):
@@ -48 +49 @@
     def delete_test_cookie(self):
         del self[TEST_COOKIE_NAME]
 
+    def get_messages(self):
+        return self.get(MESSAGES_NAME, [])
+
+    def get_and_delete_messages(self):
+        return self.pop(MESSAGES_NAME, [])
+
+    def create_message(self, message):
+        messages = self.get(MESSAGES_NAME)
+        if messages is None:
+            messages = []
+            self[MESSAGES_NAME] = messages
+        messages.append(message)
+        self.modified = True
+
     def _get_session(self):
         # Lazily loads session from storage.
         self.accessed = True

django/contrib/sessions/tests.py

@@ -10 +10 @@
 
 >>> s.pop('some key', 'does not exist')
 'does not exist'
+
+############
+# Messages #
+############
+
+>>> s.get_messages()
+[]
+
+>>> s.create_message('first post')
+>>> s.get_messages()
+['first post']
+>>> s.get_and_delete_messages()
+['first post']
+>>> s.get_and_delete_messages()
+[]
+
+>>> s.create_message('hello')
+>>> s.create_message('world')
+>>> s.get_and_delete_messages()
+['hello', 'world']
 """
 
 from django.contrib.sessions.middleware import SessionWrapper

docs/authentication.txt

@@ -911 +911 @@
 Finally, note that this messages framework only works with users in the user
 database. To send messages to anonymous users, use the `session framework`_.
 
-.. _session framework: ../sessions/
+.. _session framework: ../sessions/#visitor-messages
 
 Other authentication sources
 ============================

docs/sessions.txt

@@ -150 +150 @@
         request.session.set_test_cookie()
         return render_to_response('foo/login_form.html')
 
+Visitor Messages
+================
+
+**New in Django development version**
+
+The session message system provides a simple way to queue messages for
+anonymous site visitors. To associate messages with users in the user database,
+use the `authentication message framework`_.
+
+.. _authentication message framework: ../authentication/#messages
+
+Messages are associated with a session, therefore a message only lasts as long
+as a session is valid (see `browser-length sessions vs. persistent sessions`_).
+
+The message system relies on the session middleware and is accessed via
+``request.session``. The API is simple:
+
+    * To create a new message, use
+      ``request.session.create_message(message='message text').``
+
+    * To retreive the messages, use ``request.session.get_messages()``,
+      which returns a list of any messages (strings) in the session's queue.
+
+    * To retrieve and delete messages, use
+      ``user_obj.get_and_delete_messages()``, which returns the list of any
+      messages in the session's queue and then deletes the messages from the
+      queue.
+
+django.contrib.sessions.context_processors.visitor_messages
+-----------------------------------------------------------
+
+This `context processor`_ is provided (but not installed by default) which makes
+these messages available to the template context as the template variable
+``{{ visitor_messages }}`` when you use ``RequestContext``.
+
+.. _context processor: ../templates_python/#subclassing-context-requestcontext
+
+Here's an example of template code that displays messages::
+
+        {% if visitor_messages %}
+        <ul>
+            {% for message in visitor_messages %}
+            <li>{{ message|escape }}</li>
+            {% endfor %}
+        </ul>
+        {% endif %}
+
+Note that when this context processor is accessed by ``RequestContext``, 
+``get_and_delete_messages`` is called behind the scenes, so any messages will
+be deleted even if you don't display them.
+
 Using sessions out of views
 ===========================