1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
<?php
/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*/
namespace Piwik;
/**
* Describes a UI notification.
*
* UI notifications are messages displayed to the user near the top of the screen.
* Notifications consist of a message, a context (the message type), a priority
* and a display type.
*
* **The context** affects the way the message looks, but not how it is displayed.
*
* **The display type** determines how the message is displayed.
*
* **The priority** determines where it is shown in the list of all displayed notifications.
*
* ### Examples
*
* **Display an error message**
*
* $notification = new Notification('My Error Message');
* $notification->context = Notification::CONTEXT_ERROR;
* Notification\Manager::notify('myUniqueNotificationId', $notification);
*
* **Display a temporary success message**
*
* $notification = new Notification('Success');
* $notification->context = Notification::CONTEXT_SUCCESS;
* $notification->type = Notification::TYPE_TOAST;
* Notification\Manager::notify('myUniqueNotificationId', $notification);
*
* **Display a message near the top of the screen**
*
* $notification = new Notification('Urgent: Your password has expired!');
* $notification->context = Notification::CONTEXT_INFO;
* $notification->type = Notification::TYPE_PERSISTENT;
* $notification->priority = Notification::PRIORITY_MAX;
*
* @api
*/
class Notification
{
public const CONTEXT_SUCCESS = 'success';
public const CONTEXT_ERROR = 'error';
public const CONTEXT_INFO = 'info';
public const CONTEXT_WARNING = 'warning';
/**
* Lowest priority value.
*/
public const PRIORITY_MIN = 1;
/**
* Lower priority value.
*/
public const PRIORITY_LOW = 25;
/**
* Higher priority value.
*/
public const PRIORITY_HIGH = 50;
/**
* Highest priority value.
*/
public const PRIORITY_MAX = 100;
/**
* If this flag is applied, no close icon will be displayed. _Note: persistent notifications always have a close
* icon._
*
* See {@link $flags}.
*/
public const FLAG_NO_CLEAR = 1;
/**
* If this flag is applied, a close icon will be displayed.
*
* See {@link $flags}.
*/
public const FLAG_CLEAR = 0;
/**
* Notifications of this type will be displayed for a few seconds and then faded out.
*/
public const TYPE_TOAST = 'toast';
/**
* Notifications of this type will be displayed until the new user explicitly closes the notification.
* The notifications will display even if the user reloads the page.
*/
public const TYPE_PERSISTENT = 'persistent';
/**
* Notifications of this type will be displayed only once. They will disappear after a page reload or
* change.
*/
public const TYPE_TRANSIENT = 'transient';
/**
* The notification title. The title is optional and is displayed directly before the message content.
*
* @var string
*/
public $title;
/**
* The notification message. Must be set.
*
* @var string
*/
public $message;
/**
* Contains extra display options.
*
* Usage: `$notification->flags = Notification::FLAG_BAR | Notification::FLAG_FOO`.
*
* @var int
*/
public $flags = self::FLAG_NO_CLEAR;
/**
* The notification's display type. See `TYPE_*` constants in {@link Notification}.
*
* @var string
*/
public $type = self::TYPE_TRANSIENT;
/**
* The notification's context (message type). See `CONTEXT_*` constants in {@link Notification}.
*
* A notification's context determines how it will be styled.
*
* @var string
*/
public $context = self::CONTEXT_INFO;
/**
* The notification's priority. The higher the priority, the higher the order. See `PRIORITY_*`
* constants in {@link Notification} to see possible priority values.
*
* @var ?int
*/
public $priority;
/**
* If true, the message will not be escaped before being outputted as HTML. If you set this to
* `true`, make sure you escape text yourself in order to avoid XSS vulnerabilities.
*
* @var bool
*/
public $raw = false;
/**
* Constructor.
*
* @param string $message The notification message.
* @throws \Exception If the message is empty.
*/
public function __construct($message)
{
if (empty($message)) {
throw new \Exception('No notification message given');
}
$this->message = $message;
}
/**
* Returns `1` if the notification will be displayed without a close button, `0` if otherwise.
*
* @return int `1` or `0`.
*/
public function hasNoClear()
{
if ($this->flags & self::FLAG_NO_CLEAR) {
return 1;
}
return 0;
}
/**
* Returns the notification's priority. If no priority has been set, a priority will be set based
* on the notification's context.
*
* @return int
*/
public function getPriority()
{
if (!isset($this->priority)) {
$typeToPriority = array(static::CONTEXT_ERROR => static::PRIORITY_MAX,
static::CONTEXT_WARNING => static::PRIORITY_HIGH,
static::CONTEXT_SUCCESS => static::PRIORITY_MIN,
static::CONTEXT_INFO => static::PRIORITY_LOW);
if (array_key_exists($this->context, $typeToPriority)) {
return $typeToPriority[$this->context];
}
return static::PRIORITY_LOW;
}
return $this->priority;
}
}
|
