= Message Passing For Anonymous Users =

Proposal for 1.2: Django should include a contrib app, independent of contrib.auth, that facilitates message passing to anonymous users. 

For more information see:
 * Ticket #4604
 * http://groups.google.com/group/django-developers/browse_thread/thread/eba93088c649022b
 * http://www.caktusgroup.com/blog/2009/06/19/towards-a-standard-for-django-session-messages/

== Justification ==

Reasons why an alternative to the existing functionality ([http://docs.djangoproject.com/en/dev/topics/auth/#messages user.message_set.create]) is needed:

 * It's not possible to create messages for anonymous users
 * If the same Django user is logged in twice on different computers simultaneously, they see each others' messages 
 * User messages may get wiped even if they're not actually displayed to the user 
 * High-load sites want to avoid the unneeded database or cache usage 

Reasons why a standard needs to be endorsed by Django and a 3rd party app will not suffice:

 * The built-in implementation is broken for a large set of use cases (above); the fact that Django actively encourages this method of messaging is a bad thing
 * Reusable apps don't know what 3rd party system to use and hence cannot rely on providing session feedback 

== Existing 3rd Party Apps ==
There are a number of good, pre-existing applications out there that support more robust functionality, so there is no need to re-implement a solution from scratch for inclusion in Django.  The existing solutions can be combined or modified to meet Django's needs.  This section is meant to evaluate some of the different session/cookie message/notification engines out there for potential inclusion in Django as a contrib app.  It is a work in progress so please contribute (your notification engine here) or other changes as you see fit.

=== Criteria ===

Technical criteria necessary for inclusion in the core:

 * Support message passing for anonymous users
 * Uses the session only as a fallback: Avoid database/cache queries if possible, but support larger messages that don't fit in a cookie (> 4kb) when needed
 * Don't lose messages if they're not displayed to the user (lazy message loading)
 * Signs cookie-based messages
 * Avoids [http://docs.python.org/library/pickle.html pickling] because of the obvious security concerns
 * Provide a standard, intuitive interface so that reusable apps can provide feedback related to the current session
 * Supports different, configurable "classes" (e.g., info, warning, error, etc.) of messages

Community criteria necessary for inclusion in the core:
 * Needs community approval/support
 * Needs to be the "de facto" standard implementation

=== Available Options ===

||'''Name and Link'''||'''Anonymous user support'''||'''Session Fallback'''||'''Lazy loads messages'''||'''Signed cookies'''||'''Avoids pickling'''||'''Standard interface'''||'''Classed Messages'''||
||[http://code.google.com/p/django-notify/ django-notify]||yes||yes||yes||yes||no||yes||yes (via "tags")||
||[http://github.com/danielfm/django-flash django-flash]||yes||no||no||yes||no||no||yes (but not in a standard way)||
||[http://github.com/leah/django-flash-status django-flash-status]||yes||no||no||yes||no||yes||yes, "errors" or "statuses"||
||[http://github.com/SeanOC/django-cnotes django-cnotes]||yes||no||no||yes||no||yes||no||

 * '''yes''' means yes, always
 * '''sometimes''' means under certain conditions (e.g., an engine might support large messages if the session is used, and avoid DB access if a cookie is used, but not both)
 * '''no''' means no, not in the current implementation

Please update this table with new options or corrected information as necessary.

== Potential API ==
django-notify is the current front-runner in terms of technical features so a sampling of the potential API is included below.  Feel free to include the API(s) of other solutions as well for comparison.  Discussion of the API should take place on the [http://groups.google.com/group/django-developers/browse_thread/thread/eba93088c649022b django-developers list].

=== django-notify ===
Add the middleware to your MIDDLEWARE_CLASSES setting (after !SessionMiddleware):
{{{
    'django_notify.middleware.NotificationsMiddleware',
}}}

Add the context processor into your TEMPLATE_CONTEXT_PROCESSORS setting:
{{{
    'django_notify.context_processors.notifications',
}}}

Add a temporary notification message like this:
{{{
    request.notifications.add('Hello world.')
    # You can optionally provide a string containing tags (which is usually represented as HTML classes for the message).
    request.notifications.add('Your rating is over 9000!', 'error')
}}}

Use notifications in your template:
{{{
{% if notifications %}
<ul class="notifications">
        {% for message in notifications %}
        <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
        {% endfor %}
</ul>
{% endif %}
}}}

== Other Considerations ==

 * This app will ideally take advantage of the [wiki:Signing cookie signing API] that is also proposed for 1.2.