Index: django/core/context_processors.py =================================================================== --- django/core/context_processors.py (revision 8347) +++ django/core/context_processors.py (working copy) @@ -8,7 +8,46 @@ """ from django.conf import settings +from django.utils.encoding import StrAndUnicode +# LazyMessages is used by the `messages` and `auth` context processors. +class LazyMessages(StrAndUnicode): + """ + A lazy proxy for session and authentication messages. + """ + def __init__(self, request): + self.request = request + + def __iter__(self): + return iter(self.messages) + + def __len__(self): + return len(self.messages) + + def __nonzero__(self): + return bool(self.messages) + + def __unicode__(self): + return unicode(self.messages) + + def __getitem__(self, *args, **kwargs): + return self.messages.__getitem__(*args, **kwargs) + + def _get_messages(self): + if hasattr(self, '_messages'): + return self._messages + # First, retreive any messages for the user. + if hasattr(self.request, 'user') and \ + hasattr(self.request.user, 'get_and_delete_messages'): + self._messages = self.request.user.get_and_delete_messages() + else: + self._messages = [] + # Next, retrieve any messages for the session. + if hasattr(self.request, 'session'): + self._messages += self.request.session.get_and_delete_messages() + return self._messages + messages = property(_get_messages) + def auth(request): """ Returns context variables required by apps that use Django's authentication @@ -22,12 +61,32 @@ else: from django.contrib.auth.models import AnonymousUser user = AnonymousUser() - return { + context_extras = { 'user': user, - 'messages': user.get_and_delete_messages(), 'perms': PermWrapper(user), } + # Add authentication (and session) LazyMessages to the context too. + context_extras.update(messages(request)) + return context_extras +def messages(request): + """ + Returns messages for the session and the current user. + + Note that this processor is only useful to use explicity if you are not + using the (enabled by default) auth processor, as it also provides the + messages (by calling this method). + + The messages are lazy loaded, so no messages are retreived and deleted + unless requested from the template. + + Both contrib.session and contrib.auth are optional. If neither is provided, + no 'messages' variable will be added to the context. + """ + if hasattr(request, 'session') or hasattr(request, 'user'): + return {'messages': LazyMessages(request)} + return {} + def debug(request): "Returns context variables helpful for debugging." context_extras = {} @@ -83,3 +142,4 @@ def __iter__(self): # I am large, I contain multitudes. raise TypeError("PermWrapper is not iterable.") + Index: django/contrib/sessions/tests.py =================================================================== --- django/contrib/sessions/tests.py (revision 8347) +++ django/contrib/sessions/tests.py (working copy) @@ -16,6 +16,19 @@ '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 @@ -46,6 +59,19 @@ '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 @@ -83,6 +109,19 @@ '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) Index: django/contrib/sessions/backends/base.py =================================================================== --- django/contrib/sessions/backends/base.py (revision 8347) +++ django/contrib/sessions/backends/base.py (working copy) @@ -33,6 +33,7 @@ """ TEST_COOKIE_NAME = 'testcookie' TEST_COOKIE_VALUE = 'worked' + MESSAGES_NAME = '_messages' def __init__(self, session_key=None): self._session_key = session_key @@ -83,6 +84,20 @@ 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) Index: docs/authentication.txt =================================================================== --- docs/authentication.txt (revision 8347) +++ docs/authentication.txt (working copy) @@ -975,8 +975,11 @@ Messages ======== -The message system is a lightweight way to queue messages for given users. +The user message system is a lightweight way to queue messages for given users. +To send messages to anonymous users, use `session messages`_. +.. _session framework: ../sessions/#messages + A message is associated with a ``User``. There's no concept of expiration or timestamps. @@ -1002,24 +1005,20 @@ context_instance=RequestContext(request)) When you use ``RequestContext``, the currently logged-in user and his/her -messages are made available in the `template context`_ as the template variable -``{{ messages }}``. Here's an example of template code that displays messages:: +messages are made available in the `template context`_ as the ``{{ messages }}`` +template variable. - {% if messages %} - - {% endif %} +**New in Django development version** -Note that ``RequestContext`` calls ``get_and_delete_messages`` behind the -scenes, so any messages will be deleted even if you don't display them. +The ``{{ messages }}`` template variable will also contain session messages. +For more information, see `django.core.context_processors.messages`_. -Finally, note that this messages framework only works with users in the user -database. To send messages to anonymous users, use the `session framework`_. +.. _django.core.context_processors.messages: ../templates_python/#django-core-context_processors-messages -.. _session framework: ../sessions/ +Also note that previously, ``RequestContext`` directly called +``get_and_delete_messages`` behind the scenes, so any messages were deleted even +if not displayed. Messages are now only deleted if the ``{{ messages }}`` +variable is accessed in a template. Other authentication sources ============================ Index: docs/sessions.txt =================================================================== --- docs/sessions.txt (revision 8347) +++ docs/sessions.txt (working copy) @@ -262,6 +262,39 @@ request.session.set_test_cookie() return render_to_response('foo/login_form.html') +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 + ``request.session.get_and_delete_messages()``, which returns the list of + any messages in the session's queue and then deletes the messages from the + queue. + +The `django.core.context_processors.messages`_ context processor makes both +session messages and user messages available to templates. + +.. _django.core.context_processors.messages: ../templates_python/#django-core-context_processors-messages + Using sessions out of views =========================== Index: docs/templates_python.txt =================================================================== --- docs/templates_python.txt (revision 8347) +++ docs/templates_python.txt (working copy) @@ -346,20 +346,29 @@ logged in). See the `user authentication docs`_. * ``messages`` -- A list of messages (as strings) for the currently - logged-in user. Behind the scenes, this calls - ``request.user.get_and_delete_messages()`` for every request. That method - collects the user's messages and deletes them from the database. + logged-in user. - Note that messages are set with ``user.message_set.create``. See the - `message docs`_ for more. + **New in Django development version** + This ``messages`` list now also contains session messages. + + The messages are not retrieved and cleared (using + ``get_and_delete_messages``) until the ``messages`` variable is accessed + in a template whereas previously, this context processor called + ``request.user.get_and_delete_messages()`` behind the scenes for every + request. + + See the `authentication message docs`_ or `session message docs`_ for + information on creating messages. + * ``perms`` -- An instance of ``django.core.context_processors.PermWrapper``, representing the permissions that the currently logged-in user has. See the `permissions docs`_. .. _user authentication docs: ../authentication/#users -.. _message docs: ../authentication/#messages +.. _authentication message docs: ../authentication/#messages +.. _session message docs: ../sessions/#messages .. _permissions docs: ../authentication/#permissions django.core.context_processors.debug @@ -411,6 +420,32 @@ `HttpRequest object`_. Note that this processor is not enabled by default; you'll have to activate it. +django.core.context_processors.messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every +``RequestContext`` will contain a variable ``messages``, which is a list of +messages (as strings) for the current session and the currently logged-in user. +See the `session messages docs`_ or the `authentication messages docs`_ for more +information on using messages. + +Note that this processor is only useful if you are not using the (enabled by +default) ``auth`` processor, as it also provides the ``messages`` variable. + +The messages are not retrieved and cleared (using ``get_and_delete_messages``) +until the ``messages`` variable is accessed in a template. + +Here's an example of template code that displays messages made available by this +context processor:: + + {% if messages %} + + {% endif %} + Writing your own context processors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~