WPTRT Admin Notices

Ребята из команды, которые делают ревью тем на wp.org, представили своё отличное решение WPTRT Admin Notices для показа уведомлений в админке WordPress.
WPTRT Admin Notices — это класс, который позволяет авторам тем и плагинов добавлять уведомления для пользователей консоли WordPress.

Основной целью данного проекта является предоставление стандартизированного метода создания уведомлений в стилистике WordPress.

Уведомления, созданные с использованием этого класса, автоматически удаляются.

Внешний вид

Как использовать

$my_theme_notices = new WPTRTAdminNoticesNotices();

// Добавляем уведомление.
$my_theme_notices->add( (string) $id, (string) $title, (string) $content, (array) $options );

// Загружаем.
$my_theme_notices->boot();

Экземпляр класса Notices создается при помощи $my_theme_notices = new WPTRTAdminNoticesNotices(). А для добавления нового уведомления используется метов add().

Аргументы этого метода:

Параметр	Тип	Обязательный	Описание
$id	string	Да	Уникальный идентификатор для уведомления. Может содержать латинские буквы в нижнем оегистре и символ подчеркивания. На его основе генерится имя ключа для опции или меты у пользователя, которые записываются в базу данных.
$title	string	Да	Заголовок для вашего уведомления. Если вы не хотите использовать заголовок — передайте false.
$message	string	Да	Содержимое уведомления. Может содержать только определенные теги: <p>, <a>, <em>, <strong>.
$options	array	Нет	Дополнительные аргументы для уведомления, которые используются для изменения поведения по умолчанию.

Аргумент $options — это массив, который может содержать следующие опциональные настройки:

Ключ	Тип	Значение	По умолчанию
scope	string	Может быть global или user. Указывает, где хранить статус уведомления: в опциях или в метаданных пользователя.	global
type	string	Может принимать одно из значений: info, success, warning, error.	info
alt_style	bool	Установите true, если хотите использовать альтернативные стили для уведомления.	false
capability	string	Какие права должны быть у пользователя, чтобы он мог видеть уведомление. Подробнее о Ролях и Возможностях смотрите в статье.	edit_theme_options
screens	array	Массив идентификаторов экрана, на которых показывать уведомление. Подробнее об экранах читайте в этой статье.	[]
option_prefix	string	Префикс для генерации ключа опции или меты, в которых хранится статус уведомления.	wptrt_notice_dismissed

Примеры

Вы можете добавить этот сниппет в уже существующий код темы или плагина.

Для начала необходимо инициализировать объект Notices:

use WPTRTAdminNoticesNotices;
$my_theme_notices = new Notices();

Затем добавить простое уведомление с настройками по умолчанию:

$my_theme_notices->add(
    'my_theme_notice',                           // Уникальный ID.
    esc_html__( 'Notice Title', 'textdomain' ),  // Заголовок.
    esc_html__( 'Notice content', 'textdomain' ) // Содержимое.
);

Код из примера выше создает новое уведомление, которое будет показано на всех страницах консоли WordPress.

Когда уведомление будет закрыто, создастся запись в таблице wp_options с ключом wptrt_notice_dismissed_my_theme_notice.

Для большей кастомизации уведомления добавьте аргумент $options:

$my_theme_notices->add(
    'my_notice',                                  // Уникальный ID.
    esc_html__( 'Notice Title', 'textdomain' ),   // Заголовок.
    esc_html__( 'Notice content', 'textdomain' ), // Содержимое.
    [
        'scope'         => 'user',       // Хранить статус уведомления в метаданных пользователя.
        'screens'       => [ 'themes' ], // Показывать только на экране "Темы" screen.
        'type'          => 'warning',    // Тип уведомления предупреждение (оранжевый цвет).
        'alt_style'     => true,         // Использовать альтернативные цвета.
        'option_prefix' => 'my_theme',   // Изменить префикс меты для хранения статуса уведомления.
    ]
);

Код из примера выше создаст новое уведомление, которое будет показываться только на экране «Темы» консоли WordPress.

Когда уведомление будет закрыто, создастся запись в таблице wp_usermeta с ключём my_theme_my_notice.

Класс Notices может быть использован для добавления множества уведомлений.

После добавления нескольких уведомлений вызовите метод boot, чтобы они вывелись в консоли WordPress:

$my_theme_notices->boot();

Если собрать всё вышесказанное в одну кучу, то полный пример будет выглядеть примерно так:

$my_theme_notices = new WPTRTAdminNoticesNotices()
$my_theme_notices->add( 'my_theme_notice', __( 'Title', 'textdomain' ), __( 'Content', 'textdomain' ) );
$my_theme_notices->boot();

Autoloading

Если вам нужен будет автозагрузик классов, то можно использовать либо Composer, либо простой autoloader из самого проекта WPRTR.

Composer

В командной строке пишем:

composer require wptrt/admin-notices

WPTRT Autoloader

Если хотите подключить загрузчик от WPTRT, используйте следующий код:

include get_theme_file_path( 'path/to/autoload/src/Loader.php' );

$loader = new WPTRTAutoloadLoader();
$loader->add( 'WPTRT\AdminNotices\Notice', get_theme_file_path( 'path/to/admin-notices/src' ) );
$loader->register();

Ссылки

• WPTRT Admin Notices