Flash messaging

Whirlwind by default supports the use of flash messaging. For those unfamiliar with flash messaging, it's used to load error, info, or success messages onto the same page or a different page in response to some event or request. For example, flash messaging could be used to signal a failed login or signup attempt by loading in error messages onto the same page (via a page reload).

In order to use flash messaging, sessions must be enabled. That is, you must not disable sessions via your config file: config/settings.py. Sessions are enabled by default.

Example Use of Flash Messaging

First, create a new application (if you don't already have one from the Quickstart tutorial, yet) via the command: whirlwind-admin.py --create-application flash-messages. cd into this new application directory.

Run the server via python main.py. Then using your browser navigate to localhost:8000. Find the links, log-in and sign-up. First, try to login with unregistered credentials. You should see the flash message login not valid. Now, we'll trace how this flash message is rendered on top of this page.

Open the file application/controllers/account_controller.py. Look for the POST request handler in the LoginHandler, you should see several uses of self.flash. self.flash is the object used to store flash messages. Also note that, you must, after storing your flash messages, redirect the user to the page where you want to display the flash messages. Lastly, you should return from the handler. For instance, to show the flash message "Login not valid", here's what's done in the LoginHandler

# store the error message in the flash object
self.flash.error = "Login not valid"

# redirect the user to the page where you wish to display the
# flash message
self.redirect("/login")

# important step! Make sure to return from this handler
return

This code (after storing the flash message), sends a GET request to /login which just renders the template at views/account/login.html. It's not immediately clear how flash messages are used in the template at looking at it. But I'll show you.

login.html is a site page that "inherits" the layout page layouts/content.html. content.html includes the flash messages shared page shared/flash_messages.html. That's the file that displays flash messages. Here's the contents of flash_messages.html that we have to care about:

var message = "<ul id='flash-message-items'>";                        
% if 'error' in flash:                                                
       % for message in flash['error']:                             
               message += "<li class='error'>${message | h}</li>";   
       % endfor                                                      
% endif                                                               
% if 'notice' in flash:                                              
       % for message in flash['notice']:                             
               message += "<li class='notice'>${message | h}</li>";  
       % endfor                                                      
% endif                                                               
% if 'info' in flash:                                                 
       % for message in flash['info']:                               
               message += "<li class='info'>${message | h}</li>";    
       % endfor                                                      
 % endif                                                               
 % if 'success' in flash:                                              
       % for message in flash['success']:                            
               message += "<li class='success'>${message | h}</li>"; 
       % endfor                                                      
 % endif                                                               
message += "</ul>";                                                   
showNotification(message, '', function(){});  

This code is enclosed in <script> tags because it calls the showNotification function that's in static/js/flash-messages.js. The showNotification and hideNotification function uses jQuery to show the flash messages and hide the flash messages respectively. Make sure you load jQuery before you load the flash messages JS file. You are free to make changes to the JS in the flash-messages.js file and also make changes to flash-messages.html. But the good news is that: Every page that inherits/uses the layout page content.html can use flash messages.

If you encountered any problems during this tutorial, you can attempt to solve your problems using our FAQ.