Работая в админ-части сайта WordPress, вы периодически в верхней части окна видите уведомления системы. Они позволят узнать об ошибках, обновленных настройках, необходимых действиях и т.д. Большинство уведомлений администратора по умолчанию предоставляются WordPress “из коробки”, но плагины и темы могут добавлять свои.
По умолчанию WordPress имеет 4 типа уведомлений администратора:
- notice-success,
- notice-error,
- notice-warning,
- notice-info.
Рассмотрим детально, что из себя представляют каждое из этих уведомлений, заглянем “под капот”.
Исходный код этих различных типов уведомлений администратора в основном одинаков. Единственное различие – это имена CSS-классов и текстовые сообщения. Например, код, сгенерированный WordPress по умолчанию при отображении типичного уведомления success:
<div class="notice notice-success is-dismissible">
<p><strong>Settings saved.</strong></p>
<button type="button" class="notice-dismiss">
<span class="screen-reader-text">Закрыть это уведомление.</span>
</button>
</div> Другие уведомления схожи по структуре, но могут иметь различные названия CSS-классов, такие как settings-error, которые WordPress автоматически включает в уведомлениях администратора. Они отображаются на страницах настроек. Некоторые админ-страницы также содержат атрибут id в уведомлениях. Например, на страницах параметров отображаются следующие уведомления:
id="setting-error-settings_updated"
К счастью, нам не нужно беспокоиться об id-атрибутах и дополнительных классах, которые WordPress автоматически добавляет в уведомления администратора. При добавлении собственных уведомлений требуется только минимальная разметка:
<div class="notice notice-success is-dismissible">
<p><strong>Настройки сохранены.</strong></p>
</div> Используя этот базовый шаблон, можно создать любой тип уведомлений администратора, просто изменив имена классов и само сообщение. Все остальное остается прежним и/или обрабатывается автоматически WordPress.
Класс dismissible
В приведенном выше примере обратите внимание на класс is-dismissible, включенный во внешний элемент <div>. Он отображает кнопку Закрыть для пользователя, после нажатия которой сообщение будет закрыто.
Когда класс is-dismissible включен, WordPress автоматически добавляет разметку, используемую для отображения кнопки “x”. Таким образом, добавление этого класса – это все, что требуется для создания такого уведомления. Нужно просто использовать следующий код:
<div class="notice notice-success is-dismissible">
<p><strong>Настройки сохранены.</strong></p>
</div> В итоге:
<div class="notice notice-success is-dismissible">
<p><strong>Настройки сохранены.</strong></p>
<button type="button" class="notice-dismiss">
<span class="screen-reader-text">Закрыть это уведомление.</span>
</button>
</div> Обратите внимание, что WordPress также предоставляет CSS, необходимый для стилизации уведомления, и нужный для работы JavaScript. Чтобы проверить их работу, в админ-панели перейдите Настройки -> Общие и нажмите кнопку Сохранить изменения.
Типы уведомлений администратора
Как уже было сказано выше, WordPress по умолчанию использует 4 типа.
notice-success – отображается, когда успешно выполнена операция (обновление плагина, публикация записи).
<div class="notice notice-success is-dismissible">
<p>Успешно.</p>
</div> notice-error – когда возникла ошибка (плагин не смог быть установлен, сбой на сервере хостинга).
<div class="notice notice-error is-dismissible">
<p>Ошибка.</p>
</div> notice-warning – отображается, когда пользователь должен быть предупрежден о чем-то важном (доступно важное обновление системы или плагина).
<div class="notice notice-warning is-dismissible">
<p>Предупреждение.</p>
</div> notice-info – отображается для передачи информации пользователю (ссылки на подробную документацию или на страницу настройки).
<div class="notice notice-info is-dismissible">
<p>Информация для пользователя.</p>
</div> В коде тем и плагинов также встречаются и другие типы:
updated – сообщение с зеленой рамкой;
error – сообщение с красной рамкой;
update-nag – сообщение с желтой рамкой.
Они являются “реликвиями” из предыдущих версий WordPress и не должны использоваться. Да, они все еще работают, но считаются устаревшими в пользу вышеописанных 4-х классов.
Как добавить уведомление администратора по умолчанию?
Для страниц настроек, расположенных в админ-меню Настройки, WordPress автоматически отображает уведомления error и updated. Таким образом, если страница настроек для вашего плагина или темы находится в этом разделе, то для нее все уведомления администратора обрабатываются WordPress по умолчанию.
Для страниц настроек, расположенных в другом месте, уведомления администратора не отображаются автоматически системой. Это означает, что если настройки вашей темы или плагина находится в своем собственном меню (или в подменю любого раздела, кроме Настройки), WordPress не будет показывать сообщения автоматически. В этом случае необходимо вызвать специальную функцию settings_errors() для отображения сообщений error и updated. Для этого есть два способа.
Способ 1
Самый быстрый способ – явно добавить settings_errors() в отображаемые параметры.
<div class="wrap">
<h1>Ваше название плагина или темы</h1>
<?php settings_errors(); ?>
<form method="post" action="options.php">
.
.
.
</form>
</div> В этом случае WordPress будет отображать уведомления администратора по умолчанию при успешном обновлении настроек или при возникновении ошибки.
Способ 2
Еще один способ – добавить settings_errors() через хук admin_notices.
function wpschool_add_settings_errors() {
settings_errors();
}
add_action( 'admin_notices', 'wpschool_add_settings_errors' ); Этот код, как и в предыдущем способе, автоматически запускает хук admin_notices и отображает результаты под тегом страницы <h1>. Этот метод рекомендуется к использованию, потому что он более гибкий и расширяемый.
Добавление пользовательских уведомлений администратора
Чтобы добавить собственные уведомления, есть два способа. Для этого можно подключиться к admin_notices или использовать функцию add_settings_error(). Рассмотрим на примере оба метода.
Способ 1. Хук admin_notices
Самый простой способ отображения пользовательских уведомлений администратора – создать функцию и подключить ее к хуку admin_notices. Например:
function wpschool_custom_admin_notice() { ?>
<div class="notice notice-success is-dismissible">
<p><?php _e( 'Поздравляем. Обновление прошло успешно!', 'wpschool' ); ?></p>
</div>
<?php }
add_action( 'admin_notices', 'wpschool_custom_admin_notice' ); Здесь “wpschool” – это название плагина или темы, поэтому используется в качестве значения текстового домена для функции _e(), а также в качестве префикса имени функции. Сама функция выводит наше уведомление, которое подключается к admin_notices для отображения в админ-части WordPress. И помните, что можно изменить внешний вид уведомления, используя любой из 4-х стандартных CSS-классов (notice-success,
notice-error, notice-warning и notice-info).
Способ 2. Функция add_settings_error()
Этот метод можно использовать непосредственно в функции проверки настроек. Допустим, что наш плагин регистрирует следующую настройку:
// register_setting()
register_setting( 'my_option_group', 'my_option_group', 'my_option_group_validate' ); В результате будет вызвана включена функция my_option_group_validate().
function my_option_group_validate( $input ) {
if ( null != $input ) {
if ( false === get_option( 'my_option' ) ) {
add_option( 'my_option', $input );
} else {
update_option( 'my_option', $input );
}
}
return $input;
} Эта функция проверяет все входные данные для параметра my_option_group.
Допустим, что мы хотим отобразить пользовательское уведомление администратора в зависимости от того, соответствует ли определенный параметр нужным критериям. Поэтому вместо отображения уведомления по умолчанию “Настройки сохранены”, которое применяется ко всей группе настроек, мы хотим отобразить уведомление, которое относится к конкретному параметру. Тут и вступает в игру add_settings_error(). Мы можем отобразить пользовательскую ошибку, добавив add_settings_error() в нашу функцию проверки.
function my_option_group_validate( $input ) {
message = null;
$type = null;
if ( null != $input ) {
if ( false === get_option( 'my_option' ) ) {
add_option( 'my_option', $input );
$message = __( 'Опция добавлена.' );
$type = 'updated';
} else {
update_option( 'my_option', $input );
$message = __( 'Опция обновлена.' );
$type = 'updated';
}
} else {
$message = __( 'Возникла ошибка.' );
$type = 'error';
}
// add_settings_error()
add_settings_error( 'my_option_notice', 'my_option_notice', $message, $type );
return $input;
} Мы расширили нашу первоначальную функцию проверки с помощью некоторого условного кода. Теперь код отслеживает переменные $message и $type, которые могут использоваться функцией add_settings_error() для отображения настраиваемого уведомления в зависимости от того, что произошло с my_option. Этот метод полезен, потому что он дает нам детальный контроль над конкретными ошибками настроек и тем самым позволяет отображать точную информацию для пользователя. И это очень хорошо, потому что для реализации не требуется никаких хуков.
Способ 3. Универсальный
Хотя любой из предыдущих способов считается наилучшей практикой, иногда нужен альтернативный метод. Его можно использовать для быстрого добавления пользовательских уведомлений администратора практически в любом месте.
<?php if ( isset( $_GET['settings-updated'] ) ) : ?>
<div class="notice notice-success is-dismissible"><p><?php _e( 'Что-то произошло.' ); ?>.</p></div>
<?php endif; ?> Этот фрагмент кода использует глобальную переменную $_GET, проверяя, задано ли обновление параметров, а затем отображает базовую разметку, необходимую для отображения уведомления администратора.
Эта техника предназначена для «быстрого устранения» узких мест. Гораздо лучше использовать один из описанных выше методов для добавления уведомлений администратора.
Нажмите, пожалуйста, на одну из кнопок, чтобы узнать понравилась статья или нет.
