How to work with flash messages

  1. Summary
  2. Setting flash messages
  3. Displaying flash messages
  4. Links

Summary

Set your messages in a controller:

Yii::app()->user->setFlash('success', "Data1 saved!");
Yii::app()->user->setFlash('error', "Data2 failed!");
Yii::app()->user->setFlash('notice', "Data3 ignored.");

Display them in your view:

<?php
    foreach(Yii::app()->user->getFlashes() as $key => $message) {
        echo '<div class="flash-' . $key . '">' . $message . "</div>\n";
    }
?>

Setting flash messages

A flash message is used in order to keep a message in session through one or several requests of the same user. By default, it is removed from session after it has been displayed to the user. Flash messages are usually used in combination with HTTP redirections, because in this case there is no view, so messages can only be displayed in the request that follows redirection.

A flash message has a name and a content (AKA key and value). It is an entry of an associative array. The name is a string: often "notice", "success", or "error", but it can be anything. The content is usually a string. You can put HTML tags in your message if you display it raw. You can also set the message value to a number or an array: it will be serialized and kept in session like a string.

Flash messages can be set using the setFlash() Method of [CWebUser]. For example, if you would like to inform the user that his changes were successfully saved, you could add the following line to your Controller:

<?php
Yii::app()->user->setFlash('success', "Data saved!");
$this->redirect(array('thing/view', 'id' => 1));

In this example we used the key 'success'. If you want to define more than one flash messages, you will have to use different keys.

Displaying flash messages

To check for flash messages we use the hasFlash() Method and to obtain the flash message we use the getFlash() Method. Since Yii v1.1.3, there is also a method getFlashes() to fetch all the messages.

By default, fetching a message deletes it from the session. This means that a message is meant to be displayed only on the first page served to the user. The fetching methods have a boolean parameter that can change this behavior. See the API links in the previous paragraph.

Displaying statically

So showing of the flash message defined above in a view is done by

<?php if(Yii::app()->user->hasFlash('success')):?>
    <div class="info">
        <?php echo Yii::app()->user->getFlash('success'); ?>
    </div>
<?php endif; ?>

These few lines of code will make a flash message with the key "success" visible to the user within a div of class "info". The message will be displayed until this or another page is (re)loaded in the browser.

If you want to always display all the flash messages, then you should add a block to your layout (by default protected/views/layout/main.php). Here is a more elaborate example:

<?php
$flashMessages = Yii::app()->user->getFlashes();
if ($flashMessages) {
    echo '<ul class="flashes">';
    foreach($flashMessages as $key => $message) {
        echo '<li><div class="flash-' . $key . '">' . $message . "</div></li>\n";
    }
    echo '</ul>';
}
?>

The default CSS created by the Yii script yiic webapp has directives for three classes of flash messages on a div tag: flash-error, flash-notice, flash-success.

The best way to know if some flash messages are set is to check if Yii::app()->user->getFlashes() is empty. Since v1.1.7, Yii keeps an associative array of the flash keys in the form array("key1" => 0, ...), or null if not flash message is set. You can fetch this with Yii::app()->user->getState(CWebUser::FLASH_COUNTERS) but this is not recommended, as Yii could change this internal process.

Displaying dynamically (with Javascript)

If you want the flash message to appear somewhere above the content and then automatically fade out after a few seconds, you will have to add the following lines to your view:

<?php
Yii::app()->clientScript->registerScript(
   'myHideEffect',
   '$(".info").animate({opacity: 1.0}, 3000).fadeOut("slow");',
   CClientScript::POS_READY
);
?>

With these lines of code we register a piece of jQuery (already included with YII) javascript code, using 'myHideEffect' as ID. It will be inserted in the jQuery's ready function (CClientScript::POS_READY). Due to the chainablity of jQuery the little script will run two effects on the .info DIV sequentially:

[javascript]
    .animate({opacity: 1.0}, 3000)

Normally this would animate the .info DIV to a full opacity within 3 seconds. But the DIV is already rendered with full opacity upon page load, so calling this effect will just cause a delay for 3 seconds.

[javascript]
    .fadeOut("slow")

This is the fadeOut effect which will hide the .info DIV at slow speed.

Further readings (JS):

Links

50 0
41 followers
Viewed: 299 905 times
Version: 1.1
Category: Tutorials
Written by: pfth
Last updated by: François Gannaz
Created on: Mar 5, 2009
Last updated: 6 years ago
Update Article

Revisions

View all history

Related Articles