From 5b8d794127611b3c4887cbf8410bd69001c4ea5d Mon Sep 17 00:00:00 2001
From: diosmosis <benakamoorthi@fastmail.fm>
Date: Wed, 13 Nov 2013 12:54:58 +0000
Subject: [PATCH] Refs #4200, revised documentation of Notification classes.
---
core/DataTable.php | 2 +-
core/Notification.php | 109 +++++++++++++++++++++++++---------
core/Notification/Manager.php | 14 +++--
3 files changed, 90 insertions(+), 35 deletions(-)
diff --git a/core/DataTable.php b/core/DataTable.php
index d27564f14b..184be3b534 100644
--- a/core/DataTable.php
+++ b/core/DataTable.php
@@ -65,7 +65,7 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
*
* ### Manipulating DataTables
*
- * There are two main ways to manipulate a DataTable. You can either:
+ * There are two ways to manipulate a DataTable. You can either:
*
* 1. manually iterate through each row and manipulate the data,
* 2. or you can use predefined Filters.
diff --git a/core/Notification.php b/core/Notification.php
index 32a8f62950..83ad6fca70 100644
--- a/core/Notification.php
+++ b/core/Notification.php
@@ -11,15 +11,39 @@
namespace Piwik;
/**
- * Notification class.
- *
- * Example:
- * ```
- * $notification = new \Piwik\Notification('My Error Message');
- * $notification->context = Notification::CONTEXT_ERROR;
- * \Piwik\Notification\Manager::notify('pluginname_id', $notification);
- * ```
- *
+ * 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.
+ *
+ * A notification's context will affect the way the message looks, but not how it
+ * is displayed. A notification's display type will determine 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 Notificiation('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;
+ *
* @package Piwik
* @subpackage Notification
* @api
@@ -32,91 +56,110 @@ class Notification
const CONTEXT_WARNING = 'warning';
/**
- * Lowest priority
+ * Lowest priority value.
*/
const PRIORITY_MIN = 1;
/**
- * Lower priority
+ * Lower priority value.
*/
const PRIORITY_LOW = 25;
/**
- * Higher priority
+ * Higher priority value.
*/
const PRIORITY_HIGH = 50;
/**
- * Highest priority
+ * Highest priority value.
*/
const PRIORITY_MAX = 100;
/**
- * If flag applied, no close icon will be displayed. Please note that persistent notifications always have a close
- * icon
+ * If this flag applied, no close icon will be displayed. _Note: persistent notifications always have a close
+ * icon._
+ *
+ * See [flags](#flags).
*/
const FLAG_NO_CLEAR = 1;
/**
- * Implies transient. Notification will be displayed for a few seconds and then faded out
+ * Notifications of this type will be displayed for a few seconds and then faded out.
*/
const TYPE_TOAST = 'toast';
/**
- * Notification will be displayed until the new user explicitly closes the notification
+ * 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.
*/
const TYPE_PERSISTENT = 'persistent';
/**
- * Notification will be displayed only once.
+ * Notifications of this type will be displayed only once. They will disappear after a page reload or
+ * change.
*/
const TYPE_TRANSIENT = 'transient';
/**
- * The title of the notification. For instance the plugin name. The title is optional.
+ * The notification title. The title is optional and is displayed directly before the message content.
+ *
* @var string
*/
public $title;
/**
- * The actual message that will be displayed. Must be set.
+ * The notification message. Must be set.
+ *
* @var string
*/
public $message;
/**
- * @var int optional flags. Usage: $notification->flags = Notification::FLAG_BAR | Notification::FLAG_FOO
+ * Contains extra display options.
+ *
+ * Usage: `$notification->flags = Notification::FLAG_BAR | Notification::FLAG_FOO`.
+ *
+ * @var int
*/
public $flags = self::FLAG_NO_CLEAR;
/**
- * The type of the notification. See self::TYPE_*
+ * The notification's display type. See `TYPE_*` constants in [this class](#).
+ *
* @var string
*/
public $type = self::TYPE_TRANSIENT;
/**
- * Context of the notification. For instance info, warning, success or error.
+ * The notification's context (message type). See `CONTEXT_*` constants in [this class](#).
+ *
+ * A notification's context determines how it will be styled.
+ *
* @var string
*/
public $context = self::CONTEXT_INFO;
/**
- * The priority of the notification, the higher the priority, the higher the order. Notifications having the
- * highest priority will be displayed first and all other notifications below. See self::PRIORITY_*
+ * The notification's priority. The higher the priority, the higher the order. See `PRIORITY_*`
+ * constants in [this class](#) to see possible priority values.
+ *
* @var int
*/
public $priority;
/**
- * Set to true in case you want the raw message output. Make sure to escape the text in this case by yourself.
+ * 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 any possible XSS vulnerabilities.
+ *
* @var bool
*/
public $raw = false;
/**
+ * Constructor.
+ *
* @param string $message The notification message.
- * @throws \Exception In case the message is empty.
+ * @throws \Exception If the message is empty.
*/
public function __construct($message)
{
@@ -127,6 +170,11 @@ class Notification
$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) {
@@ -136,6 +184,12 @@ class Notification
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)) {
@@ -153,5 +207,4 @@ class Notification
return $this->priority;
}
-
}
\ No newline at end of file
diff --git a/core/Notification/Manager.php b/core/Notification/Manager.php
index 52ae50fe9b..18b231e841 100644
--- a/core/Notification/Manager.php
+++ b/core/Notification/Manager.php
@@ -14,6 +14,8 @@ use Piwik\Notification;
use Piwik\Session\SessionNamespace;
/**
+ * Posts and removes UI notifications (see [Notification](#) to learn more).
+ *
* @package Piwik
* @subpackage Notification
*/
@@ -25,13 +27,13 @@ class Manager
private static $session = null;
/**
- * Post a notification to be shown in the status bar. If a notification with the same id has already been posted
- * by your application and has not yet been canceled, it will be replaced by the updated information.
- *
- * @param string $id A unique identifier for this notification. Id must be a string and may contain only
- * word characters (AlNum + underscore)
- * @param Notification $notification
+ * Posts a notification that will be shown in Piwik's status bar. If a notification with the same id
+ * has been posted and has not been closed/removed, it will be replaced with `$notification`.
*
+ * @param string $id A unique identifier for this notification. The ID must be a valid HTML
+ * element ID. It can only contain alphanumeric characters (underscores can
+ * be used).
+ * @param Notification $notification The notification to post.
* @api
*/
public static function notify($id, Notification $notification)
--
GitLab