1: <?php
  2: /**
  3:  * Flash Helper
  4:  *
  5:  * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
  6:  * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
  7:  *
  8:  * Licensed under The MIT License
  9:  * For full copyright and license information, please see the LICENSE.txt
 10:  * Redistributions of files must retain the above copyright notice.
 11:  *
 12:  * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 13:  * @link          https://cakephp.org CakePHP(tm) Project
 14:  * @package       Cake.View.Helper
 15:  * @since         CakePHP(tm) v 2.7.0-dev
 16:  * @license       https://opensource.org/licenses/mit-license.php MIT License
 17:  */
 18: 
 19: App::uses('AppHelper', 'View/Helper');
 20: App::uses('CakeSession', 'Model/Datasource');
 21: 
 22: /**
 23:  * FlashHelper class to render flash messages.
 24:  *
 25:  * After setting messages in your controllers with FlashComponent, you can use
 26:  * this class to output your flash messages in your views.
 27:  *
 28:  * @package       Cake.View.Helper
 29:  */
 30: class FlashHelper extends AppHelper {
 31: 
 32: /**
 33:  * Used to render the message set in FlashComponent::set()
 34:  *
 35:  * In your view: $this->Flash->render('somekey');
 36:  * Will default to flash if no param is passed
 37:  *
 38:  * You can pass additional information into the flash message generation. This allows you
 39:  * to consolidate all the parameters for a given type of flash message into the view.
 40:  *
 41:  * ```
 42:  * echo $this->Flash->render('flash', array('params' => array('name' => $user['User']['name'])));
 43:  * ```
 44:  *
 45:  * This would pass the current user's name into the flash message, so you could create personalized
 46:  * messages without the controller needing access to that data.
 47:  *
 48:  * Lastly you can choose the element that is used for rendering the flash message. Using
 49:  * custom elements allows you to fully customize how flash messages are generated.
 50:  *
 51:  * ```
 52:  * echo $this->Flash->render('flash', array('element' => 'my_custom_element'));
 53:  * ```
 54:  *
 55:  * If you want to use an element from a plugin for rendering your flash message
 56:  * you can use the dot notation for the plugin's element name:
 57:  *
 58:  * ```
 59:  * echo $this->Flash->render('flash', array(
 60:  *   'element' => 'MyPlugin.my_custom_element',
 61:  * ));
 62:  * ```
 63:  *
 64:  * @param string $key The [Message.]key you are rendering in the view.
 65:  * @param array $options Additional options to use for the creation of this flash message.
 66:  *    Supports the 'params', and 'element' keys that are used in the helper.
 67:  * @return string|null Rendered flash message or null if flash key does not exist
 68:  *   in session.
 69:  * @throws UnexpectedValueException If value for flash settings key is not an array.
 70:  */
 71:     public function render($key = 'flash', $options = array()) {
 72:         if (!CakeSession::check("Message.$key")) {
 73:             return null;
 74:         }
 75: 
 76:         $flash = CakeSession::read("Message.$key");
 77: 
 78:         if (!is_array($flash)) {
 79:             throw new UnexpectedValueException(sprintf(
 80:                 'Value for flash setting key "%s" must be an array.',
 81:                 $key
 82:             ));
 83:         }
 84: 
 85:         CakeSession::delete("Message.$key");
 86: 
 87:         $out = '';
 88:         foreach ($flash as $message) {
 89:             $message['key'] = $key;
 90:             $message = $options + $message;
 91:             if ($message['element'] === 'default') {
 92:                 $message['element'] = 'Flash/default';
 93:             }
 94:             $out .= $this->_View->element($message['element'], $message);
 95:         }
 96: 
 97:         return $out;
 98:     }
 99: }
100: