Introducing admin notice functions in WordPress 6.4

Adminadmin (and super admin) notices are widely used within WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and in the extender community. Admin notices have common markup patterns and CSSCSS Cascading Style Sheets. classes, but required maintaining HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. independently for each notice throughout a project.

In #57791, two new functions were proposed: wp_get_admin_notice() and wp_admin_notice().

These functions abstract the HTML markup generation to reduce the maintenance burden, encourage consistency, and enable argument and message filtering for all admin notices. In addition, a new wp_admin_notice action has been introduced, which fires before a notice is output.

New functions

wp_get_admin_notice()

• Returns the markup for an admin notice.
• Note: The markup is not fully escaped and care should be taken to select the appropriate escaping function before output.

wp_admin_notice()

• Outputs the markup for an admin notice.
• Markup is created using wp_get_admin_notice() and escaped using wp_kses_post() before output.

Parameters

Both functions have the following parameters:

• string $message The message for the notice.
• array $args An array of arguments for the notice.
  • string $type Optional. The type of admin notice. This will be appended to 'notice-' to create the HTML class name. For example, a type of 'success' will produce a 'notice-success' HTML class. Default empty string.
  • bool $dismissible Optional. Whether the notice is dismissible. Default false.
  • string $id Optional. The value for the HTML id attribute. Default empty string.
  • array $additional_classes Optional. An array of additional class names to use for the notice. These are used as provided. Default empty array.
  • array $attributes Optional. An associative array of HTML attributes for the notice. Boolean true attributes may just include the name of the attribute. Default empty array.
  • bool $paragraph_wrap Optional. Whether to wrap the message in <p></p> tags. Default true.

Filters

wp_get_admin_notice() applies the following filters:

• wp_admin_notice_args – Filters the arguments for an admin notice.
  • Passed arguments: array $args, string $message
• wp_admin_notice_markup – Filters the markup for an admin notice.
  • Passed arguments: string $markup, string $message, array $args

Actions

wp_admin_notice() fires the following action:

• wp_admin_notice – Fires before an admin notice is output.
  • Passed arguments: string $message, array $args

Example usage

Output a dismissible success notice

wp_admin_notice(
  __( 'Plugin update failed.', 'my-text-domain' ),
  array(
    'type'               => 'error',
    'dismissible'        => true,
    'additional_classes' => array( 'inline', 'notice-alt' ),
    'attributes'         => array( 'data-slug' => 'plugin-slug' )
  )
);

Result

<div class="notice notice-error is-dismissible inline notice-alt" data-slug="plugin-slug"><p>Plugin update failed.</p></div>

Create a collection of notices to output at once 

$output = '';
foreach ( $success_messages as $message ) {
  $output .= wp_get_admin_notice(
    $message,
    array( 'type' => 'success' )
  );
}

echo wp_kses_post( $output );

Result

<div class="notice notice-success"><p>Success message 1</p></div>

(repeated for each notice)

Add a class to every ‘warning’ admin notice

add_filter( 'wp_admin_notice_args', 'myprefix_add_class_to_warnings' );
function myprefix_add_class_to_warnings( $args ) {
  if ( 'warning' === $args['type'] ) {
    $args['additional_classes'][] = 'my-class';
  }

  return $args;
}

Result

<div class="notice notice-warning my-class"><p>Warning message 1</p></div>

(repeated for each warning notice)

Usage in WordPress Core

The new admin notice functions have been implemented in most locations in WordPress Core. Further work will be done in WordPress 6.5 to complete the process and migrate older notices (using the 'updated' and 'error' classes) to the current admin notice pattern ('notice-success', 'notice-info', 'notice-warning', and 'notice-error').

Props to @joedolson and @webcommsat for peer review.

#6-4, #dev-notes, #dev-notes-6-4