Ticket #4604: visitor_messages_r6373.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/tests.py

@@ -14 +14 @@
 'dog'
 >>> db_session.pop('some key', 'does not exist')
 'does not exist'
+>>> db_session.get_messages()
+[]
+>>> db_session.create_message('first post')
+>>> db_session.get_messages()
+['first post']
+>>> db_session.get_and_delete_messages()
+['first post']
+>>> db_session.get_and_delete_messages()
+[]
+>>> db_session.create_message('hello')
+>>> db_session.create_message('world')
+>>> db_session.get_and_delete_messages()
+['hello', 'world']
 >>> db_session.save()
 >>> db_session.exists(db_session.session_key)
 True
@@ -31 +44 @@
 'dog'
 >>> file_session.pop('some key', 'does not exist')
 'does not exist'
+>>> file_session.get_messages()
+[]
+>>> file_session.create_message('first post')
+>>> file_session.get_messages()
+['first post']
+>>> file_session.get_and_delete_messages()
+['first post']
+>>> file_session.get_and_delete_messages()
+[]
+>>> file_session.create_message('hello')
+>>> file_session.create_message('world')
+>>> file_session.get_and_delete_messages()
+['hello', 'world']
 >>> file_session.save()
 >>> file_session.exists(file_session.session_key)
 True
@@ -48 +74 @@
 'dog'
 >>> cache_session.pop('some key', 'does not exist')
 'does not exist'
+>>> cache_session.get_messages()
+[]
+>>> cache_session.create_message('first post')
+>>> cache_session.get_messages()
+['first post']
+>>> cache_session.get_and_delete_messages()
+['first post']
+>>> cache_session.get_and_delete_messages()
+[]
+>>> cache_session.create_message('hello')
+>>> cache_session.create_message('world')
+>>> cache_session.get_and_delete_messages()
+['hello', 'world']
 >>> cache_session.save()
 >>> cache_session.delete(cache_session.session_key)
 >>> cache_session.exists(cache_session.session_key)

django/contrib/sessions/backends/base.py

@@ -18 +18 @@
     """
 
     TEST_COOKIE_NAME = 'testcookie'
-    TEST_COOKIE_VALUE = 'worked'
+    TEST_COOKIE_VALUE = 'worked'
+    MESSAGES_NAME = '_messages'
 
     def __init__(self, session_key=None):
         self._session_key = session_key
@@ -59 +60 @@
 
     def delete_test_cookie(self):
         del self[self.TEST_COOKIE_NAME]
-        
+
+    def get_messages(self): 
+        return self.get(self.MESSAGES_NAME, []) 
+
+    def get_and_delete_messages(self): 
+        return self.pop(self.MESSAGES_NAME, []) 
+
+    def create_message(self, message): 
+        messages = self.get(self.MESSAGES_NAME) 
+        if messages is None: 
+            messages = [] 
+            self[self.MESSAGES_NAME] = messages 
+        messages.append(message) 
+        self.modified = True 
+
     def encode(self, session_dict):
         "Returns the given session dictionary pickled and encoded as a string."
         pickled = pickle.dumps(session_dict, pickle.HIGHEST_PROTOCOL)

docs/sessions.txt

@@ -190 +190 @@
                 return HttpResponse("Please enable cookies and try again.")
         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
+all (anonymous or authenticated) 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
 ===========================

docs/authentication.txt

@@ -947 +947 @@
 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
 ============================