Функция wp_get_admin_notice() в WordPress с примерами.

Функция wp_get_admin_notice() в WordPress предназначена для генерации и возвращения HTML-кода уведомлений, которые отображаются в верхней части административной панели. Эти уведомления могут быть использованы для вывода различных сообщений, таких как ошибки, предупреждения или информационные сообщения.

wp_get_admin_notice( string $message, array $args = [] )

Описание функции

Функция wp_get_admin_notice() формирует HTML-код для уведомлений в административной панели WordPress. Уведомления могут содержать текст, HTML-контент и могут быть настроены с различными параметрами, такими как тип уведомления, возможность его закрытия и CSS-классы.

Параметры

• $message (string): Сообщение уведомления. Это обязательный параметр. Вы можете использовать HTML-код в сообщении. Всякое переданное содержимое фильтруется функцией wp_kses_post().
• $args(array, необязательный): Массив аргументов для настройки уведомления. По умолчанию пустой массив.
  • type(string, необязательный): Тип уведомления. Возможные значения:
    • success — успех
    • error — ошибка
    • warning — предупреждение
    • info — информация
    • Если не указано, используется стандартное значение.
  • dismissible (bool, необязательный): Можно ли закрыть уведомление (показать крестик). Значение не сохраняется, и уведомление будет отображаться снова после перезагрузки страницы. По умолчанию false.
  • id (string, необязательный): Значение атрибута ID для HTML-контейнера уведомления. По умолчанию пустая строка.
  • additional_classes (array, необязательный): Массив дополнительных CSS-классов для HTML-контейнера уведомления. Эти классы будут добавлены к базовым классам notice и другим в зависимости от параметров type и dismissible. По умолчанию пустой массив.
  • paragraph_wrap (bool, необязательный): Указывает, следует ли оборачивать сообщение уведомления в тег <p>. По умолчанию true.

Возвращаемое значение

Функция возвращает строку с HTML-кодом уведомления.

Пример использования

Функция wp_get_admin_notice() обычно используется в административных хуках, таких как admin_notices, network_admin_notices, user_admin_notices, и all_admin_notices. Эти хуки позволяют вставлять уведомления в нужное место в административной панели. Тем не менее, технически функцию можно вызывать в любом месте HTML-кода административной панели, и уведомление будет перемещено под заголовок с помощью JavaScript.

Предположим, вы хотите отобразить специальное уведомление для администраторов на страницах административной панели WordPress. Вы можете использовать функцию wp_get_admin_notice() для этого. Например:

// Добавляем уведомление
function my_custom_admin_notice() {
    $notice_id = 'my_custom_notice';
    $notice_message = 'Это кастомное уведомление для администраторов.';
    
    // Устанавливаем уведомление
    add_option( $notice_id, $notice_message );
}
add_action( 'admin_init', 'my_custom_admin_notice' );

// Отображаем уведомление
function my_display_admin_notice() {
    $notice_id = 'my_custom_notice';
    $notice_message = wp_get_admin_notice( $notice_id, 'Уведомление не найдено.' );
    
    echo '<div class="notice notice-info is-dismissible">';
    echo '<p>' . esc_html( $notice_message ) . '</p>';
    echo '</div>';
}
add_action( 'admin_notices', 'my_display_admin_notice' );

В этом примере функция my_custom_admin_notice() добавляет уведомление в базу данных, а функция my_display_admin_notice() отображает его в административной панели. Если уведомление с указанным идентификатором не найдено, будет отображено значение по умолчанию.

Добавление уведомления на хуке admin_head:

add_action( 'admin_head', function () {
    echo wp_get_admin_notice( 'Вывод на хуке admin_head, то есть в самом верху.' );
} );

Добавление уведомления на хуке admin_footer:

add_action( 'admin_footer', function () {
    echo wp_get_admin_notice( 'Вывод на хуке admin_footer, то есть в самом низу.' );
} );

Создание и вывод уведомления с дополнительными параметрами:

$message = wp_get_admin_notice(
    __( 'Your Custom Text', 'your-text-domain' ),
    array(
        'id'                 => 'message',
        'additional_classes' => array( 'updated' ),
        'dismissible'        => true,
    )
);

// Вывод уведомления на вашей админ-странице
echo wp_kses_post( $message );

В этом примере уведомление создается с идентификатором message, дополнительными CSS-классами updated, и опцией dismissible, которая позволяет скрыть уведомление. Функция wp_kses_post() используется для безопасного вывода HTML-кода уведомления, так как возвращаемый HTML-код не полностью экранирован.

<div id="message" class="notice is-dismissible updated"><p>Your Custom Text</p></div>

Заключение

Функция wp_get_admin_notice() предоставляет удобный способ создания и отображения уведомлений в административной панели WordPress. Она позволяет настроить тип уведомления, его внешний вид и возможность закрытия.