Flash messages (bottle_utils.flash)

Flash messages are messages that are generated in one handler and displayed to the user in another. Commonly, this is done when you want to redirect to another path and still show the results of an operation performed in another. One example would be “You have logged out” message after logging the user out.

There are several ways to do this, but storing the message in a cookie is the most straightforward. This module provides methods for doing just that.

Unicode strings are fully supported.

Basic usage

In order to make flash messaging available to your app, install the message_plugin() plugin.

bottle.install(message_plugin)

This makes bottle.request.message object and bottle.response.flash() method available to all request handlers. To set a message, use response.flash():

response.flash('This is my message')

To show the message in the interface, make the request.message object available to your template’s context and simply output it in your template:

<p class="flash">{{ message }}</p>

How it works

When a message is set, it is stored in a cookie in the user’s browser. The bottle.request.message is a lazy object (see Lazy), and does not do anything until you actually use the message. When you access the message object, it retrieves the text from the cookie and clears the cookie.

Warning

There is no mechanism for automatically clearing messages if they are not consumed. Therefore, it is important to consume it at the very next step user takes in your app. Otherwise, the message may appear on an unpexpected page at unexpected time, taken out of context, and confuse the user.

Functions and plugins

bottle_utils.flash.get_message()[source]

Return currently set message and delete the cookie. This function is lazily evaluated so it’s side effect of removing the cookie will only become effective when you actually use the message it returns.

bottle_utils.flash.message_plugin(func)[source]

Manages flash messages. This is a Bottle plugin that adds attributes to bottle.request and bottle.response objects for setting and consuming the flash messages.

See Basic usage.

Example:

bottle.install(message_plugin)
bottle_utils.flash.set_message(msg)[source]

Sets a message and makes it available via request object. This function sets the message cookie and assigns the message to the bottle.request._message attribute.

In Python 2.x, the message is UTF-8 encoded.