TurboGears provides a way to display short messages inside the current or next page. This works by using the WebFlash module which stores short text messages inside a cookie so that it can be retrieved when needed.
By Default the master.html of a quickstarted project provides a div where flash messages will be displayed, this is achieved with the following lines of code:
<py:with vars="flash=tg.flash_obj.render('flash', use_js=False)">
<div py:if="flash" py:replace="Markup(flash)" />
</py:with>
The tg.flash_obj is the WebFlash object which is available inside any rendered template. This object permits to retrieve the current flash message and display it.
Flash messages can be stored using the tg.flash command this allows to store a message with a status option to configure the flash style.
tg.flash('Message', 'status')
If the method that called flash performs a redirect the flash will be visible inside the redirected page. If the method directly exposes a template the flash will be visible inside the template itself.
When using tg_cache variable in rendered templates (Prerendered Templates Caches) the flash will get into the cached template causing unwanted messages to be displayed.
To solve this issue the tg.flash_obj.render method provides the use_js option. By default this option is set at False inside the template, changing it to True will make the flash message to be rendered using javascript. This makes so that the same template is always rendered with a javascript to fetch the flash message and display it due to the fact that the template won’t change anymore it will now be possible to correctly cache it.
By default warning, error, info, ok statuses provide a style in public/css/style.css for quickstarted applications.
Any number of statuses can be configured using plain css:
#flash > .warning {
color: #c09853;
background-color: #fcf8e3;
border-color: #fbeed5;
}
#flash > .ok {
color: #468847;
background-color: #dff0d8;
border-color: #d6e9c6;
}
#flash > .error {
color: #b94a48;
background-color: #f2dede;
border-color: #eed3d7;
}
#flash > .info {
color: #3a87ad;
background-color: #d9edf7;
border-color: #bce8f1;
}
Flash messages support can be styled using options inside the flash. namespace, those are documented in TGFlash and can be specified in config/app_cfg.py or in your .AppConfig instance.
For example to change the default message status (when status is omitted) you can use the flash.default_status option and set it to any string. To change the default flash template you can use flash.template and set it to a string with the HTML that should be displayed to show the flash (note that flash.template only works for static rendered flash, not for JS version).
For example to render the flash using the toastr library you might want to remove the py:with code block from your master.html and move it to the bottom of your <body> right after the usage of bootstrap and jquery libraries:
<body>
<!-- YOUR CURRENT BODY CONTENT -->
<script src="http://code.jquery.com/jquery.js"></script>
<script src="${tg.url('/javascript/bootstrap.min.js')}"></script>
<py:with vars="flash=tg.flash_obj.render('flash')">
<py:if test="flash">${Markup(flash)}</py:if>
</py:with>
</body>
This will ensure that we can provide custom Javascript that depends on JQuery inside our flash template. Now we can switch flash template to use the toastr library to display our flash by setting inside your app_cfg.py:
base_config['flash.default_status'] = 'success'
base_config['flash.template'] = '''\
<script src="//cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/js/toastr.min.js"></script>
<script>toastr.$status("$message");</script>
'''
This will ensure that each time the flash is displayed the toastr library with the given status is used.
Last, to correctly display the flash with the right look and feel, don’t forget to add the toastr CSS to the head of your master.html:
<link rel="stylesheet" type="text/css" media="screen"
href="//cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/css/toastr.min.css" />
If everything is correct you should see your flash messages as baloon into the top-right corner of your webpage.
Javascript based flashes are usually common when Caching is involved, so the cached version of the webpage will not have the flash inside but you still want to be able to display the flash messages. In this case instead of providing a custom flash.template you should provide a custom flash.js_call which is the javascript code used to display the message.
For example to use the toastr library you might want to ensure toastr CSS and JS are available and add the following to your app_cfg.py:
base_config['flash.default_status'] = 'success'
base_config['flash.js_call'] = '''\
var payload = webflash.payload();
if(payload) { toastr[payload.status](payload.message); }
'''
The webflash object is provided by TGFlash itself and the webflash.payload() method will fetch the current message for you.