##Requirements This extension requires Bootstrap and a Database.

##Rationale

Message

Messages have certain types('' (is a warning), 'successs', 'error', 'info'), contain a message-text, some actions and a bunch of options. A message is shown using the widget (and can optionally be destroyed upon its display).

Trigger

Messages are only shown if at least a trigger applies to the current user (Messages have one or several triggers). A trigger stores the session and/or the userID of the current User (or none of both). A trigger matches if:

1. the user is logged in and the user-id matches the id saved in the trigger
2. the session of the user matches the session saved in the trigger
3. neither the session nor the user-id of the trigger are set - this trigger will match all users in the first place. (Later more on this)

In addition to that, each trigger stores a timestamp and once that timestamp has been reached, the trigger will apply. On the other hand, you can specify a timeout so that the trigger will only apply for a certain span of time after he has been activated.

If all those conditions of a trigger are met, the trigger applies and it's associated message will be shown.

##Installation

1. Copy the files into your extension-folder

2. Import the component:

[php]

'msg' => array(
        'class' => 'application.extensions.message.ExtMessageComponent'
    ),

3. Import the tables using the install.sql

4. In the end, you must of course include the widget which displays the messages somwhere - preferrably in your layout.

[php]
echo CHtml::openTag('div', array('class' => 'messages'));
            $this->widget('application.extensions.message.widgets.MessagesWidget');
        echo CHtml::closeTag('div');;

##Usage

[php]
//Most Simplest usage
Yii::app()->msg->postMessage('info', 'This is a sample info');

//To set Options, use the second parameter
Yii::app()->msg->postMessage('', 'This is a warning!', array('modal' => true));

//To modify the trigger, use the last one
Yii::app()->msg->postMessage('', 'This is only visible for 24h', array(), 
array('timeout' => 24 * 3600));

//For detailed parameters, see the classes

//In the end, an advanced example:
 $text = "This is quite an advanced example";
 $actions = array(array(
      'caption' => 'This is a primary button',
      'url'    => '#',
      'type'   => 'primary'
    ),
    array(
      'caption' => 'This is a warning button',
      'url'     => '#',
      'type'    => 'warning',
      'size'    => 'small'
       ),
                );
Yii::app()->msg->postMessage('', $text, 
  array('title' => 'Warning!', 
        'actions' => $actions, 
        'modal' => true,
        'closAble' => true,
        'customView' => 'demo'
 ));

The advanced example above leads to this:

The advanced example without modal:

Advanced Usage with a all-matching trigger

Trigger matching every user are primarly useful if you confine the messages to users in another way - for example ACL. You can achieve this easily if you make the Triggers themselves Aco-Objects so they are bound to the regular restrictions you impose on them. Please do not try the following if you're not familiar with ACL- it's advanced.

Example:

[php]

//This shows only users of group X the message, if they haven't already seen it
//For this purpose, we'll create an aco group for each user and assign the message
// to this group if he has already seen it. If we select messages, we neglect the
//ones which are in the group already

//This script assumes that you have given only that group permission to view this
//trigger. That can be done easily using something like that:
$group = CGroup::model()->find('alias = :alias', array(':alias' => 'Allowed'));
$group->grant('view', $myTrigger);

//Second step: modify the ExtMessageComponent: directly for the findAll,
//place something like:
$userId = Yii::app()->user->id;
$group  = 'already_seen_'.$userId;
Util::addGroupRestriction('triggers', array('not', $group));


//Now, you'll want to modify the message and add something like this:
class ExtMessage{
    
    public function afterFind(){
        parent::afterFind();
        
        //Now, let the message join the group
        $userId = Yii::app()->user->id;
        $group  = 'already_seen_'.$userId;
        $this->join($group);
    }
    
}

You could enhance this if you only join the group if a certain parameter has been set in the message parameters.

##Resources

...external resources for this extension...

• This project resides on github