New event that lets plugins trigger notifications in the admin area (#11483)

* New event that lets plugins trigger notifications in the admin area

They have to be triggered before assigning the notifications to the view and there is no other way to determine when a plugin is supposed to trigger notifications in the admin. Ideally, in the future we would even move the notifications above to CoreAdminHome or somewhere else eventually.

First thought of using `Controller.addAdminNotifications` as we often use this wording but then we would need to rather do `Piwik::postEvent('Controller.triggerAdminNotifications', &$notifications);` as otherwise nothing can be added.

Plugins could actually also use this event to cancel notifications where in the past it was needed to hide them via CSS. 

Happy about any other naming suggestions but want to keep it "specific" to notifications and not something to general like `postEvent('Controller.renderAdminView, $view')`.

* document new event

1 files changed, 20 insertions, 0 deletions

diff --git a/core/Plugin/ControllerAdmin.php b/core/Plugin/ControllerAdmin.php
index 7e6c679ddf..79ce898630 100644
--- a/core/Plugin/ControllerAdmin.php
+++ b/core/Plugin/ControllerAdmin.php
@@ -325,6 +325,26 @@ abstract class ControllerAdmin extends Controller
         self::notifyWhenDebugOnDemandIsEnabled('debug');
         self::notifyWhenDebugOnDemandIsEnabled('debug_on_demand');
 
+        /**
+         * Posted when rendering an admin page and notifications about any warnings or errors should be triggered.
+         * You can use it for example when you have a plugin that needs to be configured in order to work and the
+         * plugin has not been configured yet. It can be also used to cancel / remove other notifications by calling 
+         * eg `Notification\Manager::cancel($notificationId)`.
+         *
+         * **Example**
+         *
+         *     public function onTriggerAdminNotifications(Piwik\Widget\WidgetsList $list)
+         *     {
+         *         if ($pluginFooIsNotConfigured) {
+         *              $notification = new Notification('The plugin foo has not been configured yet');
+         *              $notification->context = Notification::CONTEXT_WARNING;
+         *              Notification\Manager::notify('fooNotConfigured', $notification);
+         *         }
+         *     }
+         *
+         */
+        Piwik::postEvent('Controller.triggerAdminNotifications');
+
         $view->adminMenu = MenuAdmin::getInstance()->getMenu();
 
         $notifications = $view->notifications;