Commits

Mike Orr committed 894628e

New documentation.

  • Participants
  • Parent commits 5c75d0f

Comments (0)

Files changed (1)

File docs/index.rst

-pyramid_beaker
-==============
+pyramid_beaker_flash
+====================
+
+**pyramid_beaker_flash** is a fork of **pyramid_beaker** 0.2, adding support
+for flash messages. It's based on ``webhelpers.pylonslib.flash``, which is
+incompatible with Pyramid.  Initialization is the same as for pyramid_beaker,
+just remember to import ``pyramid_beaker_flash`` instead of ``pyramid_beaker``!
+See "Flash Messages" below for usage.
 
 A :term:`Beaker` session factory backend for :term:`Pyramid`, also cache
 configurator.
        return config.make_wsgi_app()
 
 
+
+Flash messages
+``````````````
+
+"Flash messages" are simply a queue of message strings stored in the session.
+This has two main uses: to display a status message to the user after performing
+an internal redirect, and to allow generic code to log messages for display
+without having direct access to the HTML template. The user interface consists
+of two ``session`` methods:
+
+.. method:: session.flash(message, category='notice', ignore_duplicate=False, queue='')
+
+.. method:: session.pop_messages(queue='')
+
+The ``.flash`` method appends a message to the queue, creating the queue if
+necessary. The message is not modified in any way. There's no HTML escaping,
+Unicode conversion, or wrapping in a markup object to prevent further escaping.
+If you want these, do it yourself. 
+
+The ``category`` argument names a CSS class for styling the message. The
+library does not define any categories, but users often borrow names from
+Unix's syslog facility: "critical", "error", "warning", "notice", "debug". The
+default value, "notice", fits nicely into this scheme. (Python's ``logging``
+module uses the term "info" for "notice".)
+
+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.
+
+The ``queue`` argument allows you to define multiple message queues. This can
+be used to display different kinds of messages in different places on the 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; it will not look in other queues for duplicate messages.
+(This feature corresponds to "multiple Flash objects" in
+``webhelpers.pylonslib.flash``.)
+
+The `.pop_messages`` method returns all accumulated messages as a list of
+``Message`` objects, and also empties the queue.  ``Message`` objects have two
+attributes:
+
+  * ``message``: the message text.
+  * ``category``: the message category, which is an arbitrary value defaulting
+    to "notice".
+
+Calling ``str()`` on a ``Message`` returns the message text.
+
+Implementation note: the default queue is stored as the "_messages" key in
+the session. Other queues are stored as "_messages_QUEUENAME". Each queue is a
+list of ``(category, message)`` pairs. (``Message`` objects are not stored in
+the session to avoid unplickling errors in edge cases.)
+
+
 Beaker cache region support
 ```````````````````````````