1: <?php
 2: /**
 3:  * Flash Helper
 4:  *
 5:  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
 6:  * Copyright (c) Cake Software Foundation, Inc. (http://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. (http://cakefoundation.org)
13:  * @link          http://cakephp.org CakePHP(tm) Project
14:  * @package       Cake.View.Helper
15:  * @since         CakePHP(tm) v 2.7.0-dev
16:  * @license       http://www.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:         $flash = $options + $flash;
86:         CakeSession::delete("Message.$key");
87:         $flash['key'] = $key;
88: 
89:         if ($flash['element'] === 'default') {
90:             $flash['element'] = 'Flash/default';
91:         }
92: 
93:         return $this->_View->element($flash['element'], $flash);
94:     }
95: }
96: