`webhelpers.pylonslib.flash`¶

Accumulate messages to show on the next page request.

The Flash class is useful when you want to redirect to another page and also show a status message on that page, such as “Changes saved” or “No previous search found; returning to home page”.

THE IMPLEMENTATION DEPENDS ON PYLONS. However, it can easily be adapted for another web framework.

PYRAMID USERS: use the flash methods built into Pyramid’s Session object. This implementation is incompatible with Pyramid.

A typical Pylons application instantiates a Flash object in myapp/lib/helpers.py:

from webhelpers.pylonslib.flash import Flash as _Flash
flash = _Flash()

The helpers module is then imported into your controllers and templates as h. Whenever you want to set a message, call the instance:

h.flash("Record deleted.")

You can set additional messages too:

h.flash("Hope you didn't need it.")

Now make a place in your site template for the messages. In Mako you might do:

<% messages = h.flash.pop_messages() %>
% if messages:
<ul id="flash-messages">
    % for message in messages:
    <li>${message}</li>
    % endfor
</ul>
% endif

You can style this to look however you want:

ul#flash-messages {
    color: red;
    background-color: #FFFFCC;
    font-size: larger;
    font-style: italic;
    margin-left: 40px;
    padding: 4px;
    list-style: none;
    }

Multiple flash objects¶

You can define multiple flash objects in your application to display different kinds of messages at different places on the page. For instance, you might use the main flash object for general messages, and a second flash object for “Added dookickey” / “Removed doohickey” messages next to a doohickey manager.

Message categories¶

WebHelpers 1.0 adds message categories, contributed by Wichert Akkerman. These work like severity levels in Python’s logging system. The standard categories are “warning”, “notice”, “error”, and “success”, with the default being “notice”. The category is available in the message’s .category attribute, and is normally used to set the container’s CSS class.

This is the only thing it does. Calling .pop_messages() pops all messages in the order registered, regardless of category. It is not possible to pop only a certain category, or all levels above a certain level, or to group messages by category. If you want to group different kinds of messages together, or pop only certain categories while leaving other categories, you should use multiple Flash objects.

You can change the standard categories by overriding the .categories and .default_category class attributes, or by providing alternate values using constructor keywords.

Category example¶

Let’s show a standard way of using flash messages in your site: we will demonstrate self-healing messages (similar to what Growl does on OSX) to show messages in a site.

To send a message from python just call the flash helper method:

h.flash(u"Settings have been saved")

This will tell the system to show a message in the rendered page. If you need more control you can specify a message category as well: one of warning, notice, error or success. The default category is notice. For example:

h.flash(u"Failed to send confirmation email", "warning")

We will use a very simple markup style: messages will be placed in a div with id selfHealingFeedback at the end of the document body. The messages are standard paragraphs with a class indicating the message category. For example:

<html>
  <body>
    <div id="content">
      ...
      ...
    </div>
    <div id="selfHealingFeedback">
      <p class="success">Succesfully updated your settings</p>
      <p class="warning">Failed to send confirmation email</p>
    </div>
  </body>
</html>

This can easily created from a template. If you are using Genshi this should work:

The needed CSS is very simple:

Choosing different colours for the categories is left as an exercise for the reader.

Next we create the javascript that will manage the needed behaviour (this implementation is based on jQuery):

function _SetupMessage(el) {
    var remover = function () {
        msg.animate({opacity: 0}, "slow")
           .slideUp("slow", function() { msg.remove() }); };

    msg.data("healtimer", setTimeout(remover, 10000))
       .click(function() { clearTimeout(msg.data("healtimer")); remover(); });
}

function ShowMessage(message, category) {
    if (!category)
        category="notice";

    var container = $("#selfHealingFeedback");

    if (!container.length)
        container=$("<div id='selfHealingFeedback'/>").appendTo("body");

    var msg = $("<p/>").addClass(category).html(message);
    SetupMessage(msg);
    msg.appendTo(container);
}

$(document).ready(function() {
    $("#selfHealingFeedback p").each(function() { SetupMessage($(this)); });
}

The SetupMessage function configures the desired behaviour: a message disappears after 10 seconds, or if you click on it. Removal is done using a simple animation to avoid messages jumping around on the screen.

This function is called for all messages as soon as the document has fully loaded. The ShowMessage function works exactly like the flash method in python: you can call it with a message and optionally a category and it will pop up a new message.

JSON integration¶

It is not unusual to perform a remote task using a JSON call and show a result message to the user. This can easily be done using a simple wrapper around the ShowMessage method:

function ShowJSONResponse(info) {
    if (!info.message)
        return;

    ShowMessage(info.message, info.message_category);
}

You can use this direct as the success callback for the jQuery AJAX method:

$.ajax({type: "POST",
        url:  "http://your.domain/call/json",
        dataType: "json",
        success: ShowJSONResponse
});

if you need to perform extra work in your callback method you can call it yourself as well, for example:

<form action="http://your.domain/call/form">
  <input type="hidden" name="json_url" value="http://your.domain/call/json">
  <button>Submit</button>
</form>

<sript type="text/javascript">
   $(document).ready(function() {
       $("button").click(function() {
           var button = $(this);

           button.addClass("processing");
           $.ajax({type: "POST",
                   url:  this.form["json_url"].value,
                   dataType: "json",
                   success: function(data, status) {
                       button.removeClass("processing");
                       ShowJSONResponse(data);
                    },
                    error: function(request, status, error) {
                       button.removeClass("processing");
                       ShowMessage("JSON call failed", "error");
                    }
           });

           return false;
       });
   });
</script>

This sets up a simple form which can be submitted normally by non-javascript enabled browsers. If a user does have javascript an AJAX call will be made to the server and the result will be shown in a message. While the call is active the button will be marked with a processing class.

The server can return a message by including a message field in its response. Optionally a message_category field can also be included which will be used to determine the message category. For example:

@jsonify
def handler(self):
   ..
   ..
   return dict(message=u"Settings successfully updated")

Classes¶

class webhelpers.pylonslib.flash.Flash(session_key='flash', categories=None, default_category=None)¶

Accumulate a list of messages to show at the next page request.

__call__(message, category=None, ignore_duplicate=False)¶

Add a message to the session.

message is the message text.

category is the message’s category. If not specified, the default category will be used. Raise ValueError if the category is not in the list of allowed categories.

If ignore_duplicate is true, don’t add the message if another message with identical text has already been added. If the new message has a different category than the original message, change the original message to the new category.

pop_messages()¶

Return all accumulated messages and delete them from the session.

The return value is a list of Message objects.

class webhelpers.pylonslib.flash.Message(category, message)¶

A message returned by Flash.pop_messages().

Converting the message to a string returns the message text. Instances also have the following attributes:

message: the message text.
category: the category specified when the message was created.

`webhelpers.pylonslib.flash`¶

Multiple flash objects¶

Message categories¶

Category example¶

JSON integration¶

Classes¶

Table Of Contents

Previous topic

Next topic

webhelpers.pylonslib.flash¶

Multiple flash objects¶

Message categories¶

Category example¶

JSON integration¶

Classes¶

`webhelpers.pylonslib.flash`¶