Admin Notices

Admin notices refer to the notification-style messages that appear at the top of the WordPress admin dashboard. The SDK uses an object model for notices, allowing notices to be injected as dependencies into other services.

Usage

A notice instance can be created via its constructor:

use RebelCode\WpSdk\Wp\Notice;

$notice = new Notice(
    Notice::INFO,    // Type (used to color the notice)
    'my-notice',     // ID (used in the HTML)
    'Hello, world!'  // Message HTML content
);

The notice type can be one of the following:

Notice::INFO;     // cyan
Notice::SUCCESS;  // green
Notice::WARNING;  // yellow
Notice::ERROR;    // red
Notice::NONE;     // no color

Alternatively, static constructors for each type are also available:

use RebelCode\WpSdk\Wp\Notice;

Notice::info('my-notice', 'There is something you should know!');
Notice::warning('my-notice', 'Things may not have gone as planned.');
Notice::error('my-notice', 'You done goofed.');
Notice::success('my-notice', 'Operation completed successfully.');

Rendering

A notice can be shown on the admin dashboard by calling its render() method. This method will return the notice's HTML content, which you can simply echo:

use RebelCode\WpSdk\Wp\Notice;

$notice = Notice::info('my-notice', 'Hello, world!');

echo $notice->render();

Alternatively, you can also obtain a function that echoes the notice. This can be very useful as a hook callback:

$callback = $notice->getEchoFn();

// Call the function to echo the notice
$callback();

// Pass the function as a hook callback
add_action('admin_notices', $callback);

Dismissible notices

If a notice is dismissible, you can also pass an Option instance to record whether the notice has been dismissed by the user.

use RebelCode\WpSdk\Wp\Notice;
use RebelCode\WpSdk\Wp\Option;

$option = new Option(Option::BOOL, 'my_notice_dismissed', false);
$notice = new Notice(Notice::INFO, 'my-notice', 'Hello, world!', true, $option);

Refer to the documentation on Options for more information.

Dismissible notices require a script to be loaded in the browser. This script will send an async request to the server to update the notice's option when the user dismisses the notice. This script can be enqueued using the NoticeManager.

use RebelCode\WpSdk\Wp\NoticeManager;

$manager = new NoticeManager(/*...*/);

echo $manager->getScript('my-notice');

You can also programmatically dismiss a notice, should you need to do so:

// Dismiss the notice directly
$notice->dismiss();

// Dismiss it through the manager using the notice's ID
$manager->dismiss('my-notice');

Note 1: You are not required to provide the server-side code for this async request. The SDK will automatically handle these requests for you.

Note 2: The script can be automatically enqueued by the SDK. The next section will cover this.

Notice Manager

The SDK includes a NoticeManager class that can be used to manage notices. Notices can be registered to this class with an ID, and then later rendered using that ID.

use RebelCode\WpSdk\Wp\NoticeManager;

$manager = new NoticeManager(
    // nonce action for async requests
    'my_plugin',
    // AJAX action for async requests
    'my_plugin_dismiss_notice',
    // List of notices
    [
        new Notice(Notice::INFO, 'my-notice', 'Hello, world!')
    ]
);

// Add a new notice
$notice = new Notice(Notice::INFO, 'ask-for-review', 'Please review my plugin!');
$manager->add($notice);

// Show the notices
$manager->show('ask-for-review');
$manager->show('my-notice');

When rendering notices from the manager, the manager will automatically check if the notice is dismissible and load the script to handle the AJAX request to update the option. You don't need to load the script yourself.

Services

Factories for notices can be easily created using the Notice::factory() static method:

use RebelCode\WpSdk\Wp\Notice;

class MyModule extends Module
{
    public function getFactories(): array
    {
        return [
            'my_notice' => Notice::factory(
                Notice::INFO,
                'my-notice',
                'Hello, world!',
                true,
                'my_notice_dismissed'
            ),
        ];
    }
}

Notices can be registered to the NoticeManager by extending the wp/notices service with your notice instances.

use Dhii\Services\Extensions\ArrayExtension;

class MyModule extends Module
{
    public function getFactories(): array
    {
        return [
            'my_notice' => /* ... */,
        ];
    }

    public function getExtensions(): array
    {
        return [
            'wp/notices' => new ArrayExtension(['my_notice']),               
        ];
    }
}

The notices in this array service will be automatically added to the wp/notices/manager service.