Teknik is a suite of services with attractive and functional interfaces. https://www.teknik.io/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

Notification.php 5.6KB

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