userflash Follow @yiiframework

Use this widget if you

• don't want to code the rendering of the flashes in the view
• want to render multiple flash messages
• want to combine user flashes and logging
• want to use one or more context terms (or none) instead of always have to use flash keys
• want to display the flash messages with jquery effects
• want to set a css class on generating the message
• want to display user flash messages as javascript alert or as ajax response

New in v.1.5: Support for bootstrap alerts

Requirements ¶

Developed with Yii 1.1.8, should work with 1.1.6 +

Usage ¶

Extract the file 'EUserFlash.php' into protected/extensions

You have to use the static methods of EUserFlash to generate flash messages. Flash messages added with 'Yii::app()->user->setFlash()' will not be rendered.

The standard messages

• EUserFlash::setNoticeMessage($message,$context='',$logLevel='')
• EUserFlash::setSuccessMessage($message,$context='',$logLevel='')
• EUserFlash::setErrorMessage($message,$context='',$logLevel=CLogger::LEVEL_ERROR)
• EUserFlash::setWarningMessage($message,$context='',$logLevel=CLogger::LEVEL_WARNING)

You can define a context (list of keywords separated with a ',') when creating a message. You can register one or more terms of the context in the view when rendering the widget (see view code below)

If you want to log the message on rendering you have to set a logLevel. On logging, additional info will be added:

• user, ip address, controller route
• if messageType='error', $_GET and $_POST vars too (more info configurable)

The log category will be: 'userflash.messageType.context'. For example 'userflash.error', 'userflash.warning.login.activate' ....

The widget renders the message inside a 'div' tag with the corresponding css classes:

• flash-notice, flash-success, flash-error (default in blueprint css)
• flash-warning (you have to add to your css)

The javascript messages

The wiget will render these types as javacript alert / ajax response

• EUserFlash::setAlertMessage($message,$context='',$logLevel='')
• EUserFlash::setAjaxMessage($url,$context='',$logLevel='')

The custom method

Use the base method 'setMessage' to create own messageTypes (css-classes, loglevel...) You can set your own cssClass when generating the message (if empty it will be 'flash-default').

• EUserFlash::setMessage($message,$context='',$cssClass='',$logLevel='',$messageType='default')

Controller code example:

Yii::import('ext.EUserFlash');
 
...
EUserFlash::setSuccessMessage('This is a success message.');
...
//An error message with the context login and activate
//The widget must register one of the context terms for rendering this flash message 
EUserFlash::setErrorMessage('This is a error message.','login,activate');
...
 
//display the message as javascript alert
EUserFlash::setAlertMessage('Hello world');
 
//display the message inside the 'div' with content from a ajax response
$url = $this->createUrl('userflash/id/1');
EUserFlash::setAjaxMessage($url);

If you add multiple lines in a controller actions code. You decide in the view, which of these messages (or all) you want to render.

The view code - $this is the controller in the view:

<?php
   //this will render all flashes, independent of the context
   $this->widget('ext.EUserFlash');
 
   //this is equivalent, but will return the count of rendered message if needed
   //see Special usage
   EUserFlash::renderFlashes($this);
 
  ?>
 
<?php
   //this will render all messages, generated with empty context
   $this->widget('ext.EUserFlash',array('context'=>''));
   //the same
   EUserFlash::renderFlashes($this,array('context'=>''));
?>
 
<?php
 
   //this will render all messages with the context 'login'
   //inside a span with the class my-flash-error-class' if an error message is rendered.
   //use EUserFlash::renderFlashes(...) the same way.
   $this->widget('ext.EUserFlash',array(
           'context'=>'login',
           'cssClassError'=>'my-flash-error-class',   
           'tag'=>'span'
      ));
?>
 
<?php
   //this will render all messages with the context 'login' or 'activate'
   $this->widget('ext.EUserFlash',array('context'=>'login,activate'));
?>
 
 
<?php
   //all options with the default values
   //see the comments in the code
 
   $this->widget('ext.EUserFlash',
        array(
                'loggingEnabled' = true,
                'errorLogVars' = array('_GET','_POST'),
                'context'=>null,
                'deleteMessages' = true,
                'tag' = 'div',
                'cssClassDefault' = 'flash-default',
                'cssClassNotice' = 'flash-notice',
                'cssClassError' = 'flash-error',   
                'cssClassWarning' = 'flash-warning',  
                'cssClassSuccess' = 'flash-success',  
                'initScript'=>null, 
                'htmlOptions' = array() 
 
          ));
?>

Special usage ¶

If you have to change the output in the view depending on rendered messages you have to use the static method 'renderFlashes' instead of $this->widget('ext.EUserFlash'...); This is because the widget run method has no return value.

Your code in the view - $this is the controller

<?php if (!EUserFlash::renderFlashes($this,array('context'=>'loginerror')): ?>
  ...
  // output if no message with the context 'loginerror' is rendered 
   ...
<?php endif; ?>

'renderFlashes' returns 'renderedCount', so you can do something like this in the view too:

if (($count = EUserFlash::renderFlashes($this,array('context'=>''))) > 0)
     echo $count . ' messages rendered';
   else
     echo 'No messages rendered';

Effects ¶

If the property initScript of the widget is assigned, this string will be rendered as js-code (clientScript). Use this property to add jquery code for effects. You can use the always added css classes 'userflash' and depending on the messageType: userflash_success, userflash_error ... to select the 'div' tags and assign effect (or other) jquery methods like fadeIn, fadeOut, animate ...

//fade out the success and notice messages, error and warning with no effects
$this->widget('ext.EUserFlash',array(
 'initScript'=>"$('.userflash_success').fadeOut(10000);$('.userflash_notice').fadeOut(10000);"
));
 
//fade in all messagetypes
$this->widget('ext.EUserFlash',array(
  'initScript'=>"$('.userflash').fadeIn(3000);",
  ));
 
//fade in and out notice messages
$this->widget('ext.EUserFlash',array(
  'initScript'=>"$('.userflash_notice').fadeIn(3000).fadeOut(10000);",
  ));

You can play around with chained methods animate(...).animate(...) too or other jquery stuff (fancybox ...).

Bootstrap ¶

Since v1.5 this extension supports the twitter bootstrap layout. If you have installed the bootstrap css and js scripts (by a Yii extension or manually) you can display the messages as bootstrap alerts.

You only have to set the property 'bootstrapLayout'=>true:

$controller->widget('ext.EUserFlash',array(
            'bootstrapLayout' => true,
 
            // These messageTypes will be rendered with the closebutton 'x'
            //'bootstrapCloseButtons' => array('warning','notice','error','success'), //default
 
            //The class of the bootstrap modal 
            //used as replacement for the js-alert message (EUserFlash::setAlertMessage()
            //'bootstrapModalClass' => 'hide', //default, or 'hide fade'
 
            // The caption for the closebutton of the bootstrap modal
            //'bootstrapCloseButtonText' => 'Ok', //default          
        ));

Changlog ¶

• v1.5 add bootstrap layout support
• v1.4.1 bugfix: $this in the static method EUserFlash::renderFlashes
• v1.4 added methods setAjaxMessage,setAlertMessage
• v1.3 added initScript property for jquery effects, css classes 'userflash', 'userflash_success' ...
• v1.2 added logging feature, added method setWarningMessage

Similar extensions ¶

• yii-flash
• messagestack