diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api.rst | 1 | ||||
| -rw-r--r-- | docs/api/flash.rst | 36 | ||||
| -rw-r--r-- | docs/api/interfaces.rst | 1 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/latexindex.rst | 2 | ||||
| -rw-r--r-- | docs/narr/flash.rst | 123 | ||||
| -rw-r--r-- | docs/narr/sessions.rst | 4 |
7 files changed, 168 insertions, 0 deletions
diff --git a/docs/api.rst b/docs/api.rst index b650c8ded..4808a08b3 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -15,6 +15,7 @@ documentation is organized alphabetically by module name. api/config api/events api/exceptions + api/flash api/httpexceptions api/i18n api/interfaces diff --git a/docs/api/flash.rst b/docs/api/flash.rst new file mode 100644 index 000000000..94907958d --- /dev/null +++ b/docs/api/flash.rst @@ -0,0 +1,36 @@ +.. _flash_module: + +:mod:`pyramid.flash` +-------------------- + +Flash Category Constants +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following attributes represent constants for use as flash messaging +category values (see :ref:`flash_chapter`). + +.. attribute:: DEBUG + + An alternate spelling for the string ``debug``. Represents development + debug messages. + +.. attribute:: INFO + + An alternate spelling for the string ``info``. Represents messages that + are informational for user consumption. + +.. attribute:: SUCCESS + + An alternate spelling for the string ``success``. Represents messages that + tell the user about a successful action. + +.. attribute:: WARNING + + An alternate spelling for the string ``warning``. Represents messages + that tell the user about a condition that is not a success, but is neither + an error. + +.. attribute:: ERROR + + An alternate spelling for the string ``success``. Represents messages + that tell the user about an unsuccessful action. diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst index b3c14e5f7..dab64ba15 100644 --- a/docs/api/interfaces.rst +++ b/docs/api/interfaces.rst @@ -35,3 +35,4 @@ Other Interfaces .. autointerface:: ITemplateRenderer + .. autointerface:: IFlashMessages diff --git a/docs/index.rst b/docs/index.rst index 4f484b0f9..fbf9de810 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,6 +48,7 @@ Narrative documentation in chapter form explaining how to use narr/static narr/webob narr/sessions + narr/flash narr/security narr/hybrid narr/i18n diff --git a/docs/latexindex.rst b/docs/latexindex.rst index f55e30aa8..6a1992ba4 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -41,6 +41,7 @@ Narrative Documentation narr/static narr/webob narr/sessions + narr/flash narr/security narr/hybrid narr/i18n @@ -88,6 +89,7 @@ API Reference api/config api/events api/exceptions + api/flash api/httpexceptions api/i18n api/interfaces 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 --------------------------------- |