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/api/interfaces.rst | 1 - docs/narr/flash.rst | 126 +++++++++++++++++++++--------------------------- 2 files changed, 55 insertions(+), 72 deletions(-) (limited to 'docs') diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst index dab64ba15..b3c14e5f7 100644 --- a/docs/api/interfaces.rst +++ b/docs/api/interfaces.rst @@ -35,4 +35,3 @@ Other Interfaces .. autointerface:: ITemplateRenderer - .. autointerface:: IFlashMessages 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