- Added flash messaging, as described in the "Flash Messaging" narrative

  documentation chapter.

2 files changed, 127 insertions, 0 deletions

diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst
new file mode 100644
index 000000000..331793533
--- /dev/null
+++ b/docs/narr/flash.rst
@@ -0,0 +1,123 @@
+.. _flash_chapter:
+
+Flash Messages
+==============
+
+"Flash messages" are simply a queue of message strings stored in the
+:term:`session`.  To use flash messaging, you must enable a :term:`session
+factory` as described in :ref:`using_the_default_session_factory` or
+:ref:`using_alternate_session_factories`.
+
+Flash messaging has two main uses: to display a status message only once to
+the user after performing an internal redirect, and to allow generic code to
+log messages for single-time display without having direct access to an HTML
+template. The user interface consists of two methods of the :term:`session`
+object.
+
+Using the ``session.flash`` Method
+----------------------------------
+
+To add a message to a flash queue, use a session object's ``flash`` method:
+
+.. code-block:: python
+   :linenos:
+
+   request.session.flash('mymessage')
+
+The ``.flash`` method appends a message to the queue, creating the queue if
+necessary. The message is not modified in any way.
+
+The ``category`` argument names a category or level. The library defines
+several default category names: ``debug``, ``info``, ``success``, ``warning``
+and ``error``.  The default category level is ``info``.
+
+The ``queue_name`` argument allows you to define multiple message
+queues. This can be used to display different kinds of messages in different
+places on a page.  You cam pass any name for your queue, but it must be a
+string. The default value is the empty string, which chooses the default
+queue. Each queue is independent, and can be popped by ``unflash``
+separately.
+
+Constant names for flash message category names are importable from the
+:mod:`pyramid.flash` module as ``DEBUG``, ``INFO``, ``SUCCESS``, ``WARNING``
+and ``ERROR``, which respectively name ``debug``, ``info``, ``success``,
+``warning`` and ``error`` strings.  For example you can do this:
+
+.. code-block:: python
+
+   from pyramid import flash
+   request.session.flash(msg, flash.DEBUG)
+
+Or you can use the literal name ``debug``:
+
+.. code-block:: python
+
+   request.session.flash(msg, 'debug')
+
+Both examples do the same thing.  The meanings of flash category names are
+detailed in :mod:`pyramid.flash`.
+
+To pop a particular queue of messages from the flash object, use the session
+object's ``unflash`` method.
+
+.. code-block:: python
+   :linenos:
+
+   >>> request.session.flash('info message', 'info')
+   >>> messages = request.session.unflash()
+   >>> messages['info']
+   ['info message']
+
+Using the ``session.unflash`` Method
+------------------------------------
+
+Once one or more messages has been added to a flash queue by the
+``session.flash`` API, the ``session.unflash`` API can be used to pop that
+queue and return it for use.
+
+For example some code that runs in a view callable might call the
+``session.flash`` API:
+
+.. code-block:: python
+   :linenos:
+
+   request.session.flash('mymessage')
+   
+A corresponding ``session.unflash`` might be called on a subsequent request:
+
+.. code-block:: python
+   :linenos:
+
+   messages = request.session.unflash()
+
+Calling ``session.unflash`` again like above without a corresponding call to
+``session.flash`` will return an empty ``messages`` object, because the queue
+has already been popped.
+
+The ``messages`` object returned from ``unflash`` is a dictionary-like
+object.  Its keys are category names, and its values are sequences of
+strings.  For ease of use, the dict-like object returned by ``unflash`` isn't
+a "plain" dict: it's an object which has several helper methods, each named
+after a particular flash category level.  These methods return all messages
+related to the category name:
+
+.. code-block:: python
+   :linenos:
+
+   >>> request.session.flash('debug message', 'debug')
+   >>> request.session.flash('info message', 'info')
+   >>> messages = request.session.unflash()
+   >>> info_messages = messages.debug()
+   ['debug message']
+   >>> info_messages = messages.info()
+   ['info message']
+
+The full API of the ``messages`` object returned by ``unflash`` is documented
+in :class:`pyramid.interfaces.IFlashMessages`.
+
+.. The ``ignore_duplicate`` flag tells whether to suppress duplicate
+.. messages.  If true, and another message with identical text exists in the
+.. queue, don't add the new message. But if the existing message has a
+.. different category than the new message, change its category to match the
+.. new message.
+
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 7a0a03384..de9add3b7 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -10,6 +10,8 @@ A :term:`session` is a namespace which is valid for some period of
 continual activity that can be used to represent a user's interaction
 with a web application.
 
+.. _using_the_default_session_factory:
+
 Using The Default Session Factory
 ---------------------------------
 
@@ -131,6 +133,8 @@ Some gotchas:
    single: pyramid_beaker
    single: Beaker
 
+.. _using_alternate_session_factories:
+
 Using Alternate Session Factories
 ---------------------------------