From 4df636c0d7734a8b80b17c78f57968466d558844 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 22 Dec 2010 01:25:15 -0500 Subject: - Added flash messaging, as described in the "Flash Messaging" narrative documentation chapter. --- docs/narr/flash.rst | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/narr/flash.rst (limited to 'docs/narr/flash.rst') 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. + -- cgit v1.2.3 From 6f6d3649b280d3585d4c48541cac14e3959f9776 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 22 Dec 2010 16:57:23 -0500 Subject: change flash API as per email convo with Ben and Mike --- docs/narr/flash.rst | 126 +++++++++++++++++++++++----------------------------- 1 file changed, 55 insertions(+), 71 deletions(-) (limited to 'docs/narr/flash.rst') diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst index 331793533..d41c2cdaf 100644 --- a/docs/narr/flash.rst +++ b/docs/narr/flash.rst @@ -11,113 +11,97 @@ factory` as described in :ref:`using_the_default_session_factory` or 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. +template. The user interface consists of a number of 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: +To add a message to a flash message 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 ``.flash`` method appends a message to a flash queue, creating the queue +if necessary. -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``. +``.flash`` accepts three arguments: -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. +.. method:: flash(message, queue='', allow_duplicate=True) -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: +The ``message`` argument is required. It represents a message you wish to +later display to a user. It is usually a string but the ``message`` you +provide is not modified in any way. -.. code-block:: python +The ``queue`` argument allows you to choose a queue to which to append the +message you provide. This can be used to push different kinds of messages +into flash storage for later display 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 ``pop_flash`` or examined via ``peek_flash`` separately. +``queue`` defaults to the empty string. The empty string represents the +default flash message queue. - from pyramid import flash - request.session.flash(msg, flash.DEBUG) +.. code-block:: python -Or you can use the literal name ``debug``: + request.session.flash(msg, 'myappsqueue') -.. code-block:: python +The ``allow_duplicate`` argument, which defaults to ``True``. If this is +``False``, if you attempt to add a message to a queue which is already +present in the queue, it will not be added. - request.session.flash(msg, 'debug') +Using the ``session.pop_flash`` Method +-------------------------------------- -Both examples do the same thing. The meanings of flash category names are -detailed in :mod:`pyramid.flash`. +Once one or more messages has been added to a flash queue by the +``session.flash`` API, the ``session.pop_flash`` API can be used to pop that +queue and return it for use. To pop a particular queue of messages from the flash object, use the session -object's ``unflash`` method. +object's ``pop_flash`` method. .. code-block:: python :linenos: - >>> request.session.flash('info message', 'info') - >>> messages = request.session.unflash() - >>> messages['info'] + >>> request.session.flash('info message') + >>> request.session.pop_flash() ['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: +Calling ``session.pop_flash()`` again like above without a corresponding call +to ``session.flash`` will return an empty list, because the queue has already +been popped. .. code-block:: python :linenos: - request.session.flash('mymessage') - -A corresponding ``session.unflash`` might be called on a subsequent request: - -.. code-block:: python - :linenos: + >>> request.session.flash('info message') + >>> request.session.pop_flash() + ['info message'] + >>> request.session.pop_flash() + [] - messages = request.session.unflash() +The object returned from ``pop_flash`` is a list. -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. +Using the ``session.pop_flash`` Method +-------------------------------------- -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: +Once one or more messages has been added to a flash queue by the +``session.flash`` API, the ``session.peek_flash`` API can be used to "peek" +at that queue. Unlike ``session.pop_flash``, the queue is not popped from +flash storage. .. 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() + >>> request.session.flash('info message') + >>> request.session.peek_flash() ['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. - + >>> request.session.peek_flash() + ['info message'] + >>> request.session.pop_flash() + ['info message'] + >>> request.session.peek_flash() + [] -- cgit v1.2.3