[Documentation Request] What is the way to notify users in Admin2?

[3e33]

With Admin2 there have been changes to how messages are displayed, what do plugin devs now need to use to notify users of errors, warnings etc... on the Admin page? For example if a user has hit the Save button on a new page, but a plugin detects something wrong with the markdown content, how do we stop the save and notify the user to fix it? Or continue the process, but show a notification?

[3e33]

After doing a lot of digging I believe there's an example in the Login plugin, but there's not much information on how it works.

    /**
     * [onApiDashboardNotifications] Admin-next (admin2) notice.
     *
     * Contributes the same untrusted-host warning as a persistent, dismissible
     * dashboard banner in the `top` location. Dismissal and reappearance flow
     * through the API plugin's standard notification handling.
     *
     * @param Event $event
     * @return void
     */
    public function onApiDashboardNotifications(Event $event): void
    {
        if (Email::isTrustedHostConfigured()) {
            return;
        }

        $notifications = $event['notifications'] ?? [];
        $notifications['top'][] = [
            'id'             => 'login-untrusted-host',
            'date'           => date('c'),
            'level'          => 'warning',
            'icon'           => 'shield-alert',
            'location'       => ['top'],
            'message'        => $this->grav['language']->translate('PLUGIN_LOGIN.UNTRUSTED_HOST_NOTICE'),
            'reappear_after' => '+7 days',
        ];
        $event['notifications'] = $notifications;
    }

[rhukster]

Good idea, i'll add something.