Changeset 56408

Timestamp:

08/17/2023 08:27:35 PM (16 months ago)

Author:

joedolson

Message:

Administration: Add function to standardize admin notices.

Add functions wp_get_admin_notice() and wp_admin_notice() to create and output admin notices & tests for usage. New functions accept a message and array of optional arguments. This commit does not implement the functions. Include new filters: wp_admin_notice_args, wp_admin_notice_markup and action: wp_admin_notice.

Props joedolson, costdev, sakibmd, dasnitesh780, sabernhardt.
Fixes #57791.

Location:

trunk

Files:

• src/wp-admin/includes/misc.php (modified) (1 diff)
• tests/phpunit/tests/admin/wpAdminNotice.php (added)
• tests/phpunit/tests/admin/wpGetAdminNotice.php (added)

trunk/src/wp-admin/includes/misc.php

@@ -1643 +1643 @@
     return $response;
 }
+
+/**
+ * Creates and returns the markup for an admin notice.
+ *
+ * @since 6.4.0
+ *
+ * @param string $message The message.
+ * @param array  $args {
+ *     Optional. An array of arguments for the admin notice. Default empty array.
+ *
+ *     @type string   $type               Optional. The type of admin notice.
+ *                                        For example, 'error', 'success', 'warning', 'info'.
+ *                                        Default empty string.
+ *     @type bool     $dismissible        Optional. Whether the admin notice is dismissible. Default false.
+ *     @type string   $id                 Optional. The value of the admin notice's ID attribute. Default empty string.
+ *     @type string[] $additional_classes Optional. A string array of class names. Default empty array.
+ *     @type bool     $paragraph_wrap     Optional. Whether to wrap the message in paragraph tags. Default true.
+ * }
+ * @return string The markup for an admin notice.
+ */
+function wp_get_admin_notice( $message, $args = array() ) {
+    $defaults = array(
+        'type'               => '',
+        'dismissible'        => false,
+        'id'                 => '',
+        'additional_classes' => array(),
+        'paragraph_wrap'     => true,
+    );
+
+    $args = wp_parse_args( $args, $defaults );
+
+    /**
+     * Filters the arguments for an admin notice.
+     *
+     * @since 6.4.0
+     *
+     * @param array  $args    The arguments for the admin notice.
+     * @param string $message The message for the admin notice.
+     */
+    $args    = apply_filters( 'wp_admin_notice_args', $args, $message );
+    $id      = '';
+    $classes = 'notice';
+
+    if ( is_string( $args['id'] ) ) {
+        $trimmed_id = trim( $args['id'] );
+
+        if ( '' !== $trimmed_id ) {
+            $id = 'id="' . $trimmed_id . '" ';
+        }
+    }
+
+    if ( is_string( $args['type'] ) ) {
+        $type = trim( $args['type'] );
+
+        if ( str_contains( $type, ' ' ) ) {
+            _doing_it_wrong(
+                __FUNCTION__,
+                sprintf(
+                    /* translators: %s: The "type" key. */
+                    __( 'The %s key must be a string without spaces.' ),
+                    '<code>type</code>'
+                ),
+                '6.4.0'
+            );
+        }
+
+        if ( '' !== $type ) {
+            $classes .= ' notice-' . $type;
+        }
+    }
+
+    if ( true === $args['dismissible'] ) {
+        $classes .= ' is-dismissible';
+    }
+
+    if ( is_array( $args['additional_classes'] ) && ! empty( $args['additional_classes'] ) ) {
+        $classes .= ' ' . implode( ' ', $args['additional_classes'] );
+    }
+
+    if ( false !== $args['paragraph_wrap'] ) {
+        $message = "<p>$message</p>";
+    }
+
+    $markup = sprintf( '<div %1$sclass="%2$s">%3$s</div>', $id, $classes, $message );
+
+    /**
+     * Filters the markup for an admin notice.
+     *
+     * @since 6.4.0
+     *
+     * @param string $markup  The HTML markup for the admin notice.
+     * @param string $message The message for the admin notice.
+     * @param array  $args    The arguments for the admin notice.
+     */
+    return apply_filters( 'wp_admin_notice_markup', $markup, $message, $args );
+}
+
+/**
+ * Outputs an admin notice.
+ *
+ * @since 6.4.0
+ *
+ * @param string $message The message to output.
+ * @param array  $args {
+ *     Optional. An array of arguments for the admin notice. Default empty array.
+ *
+ *     @type string   $type               Optional. The type of admin notice.
+ *                                        For example, 'error', 'success', 'warning', 'info'.
+ *                                        Default empty string.
+ *     @type bool     $dismissible        Optional. Whether the admin notice is dismissible. Default false.
+ *     @type string   $id                 Optional. The value of the admin notice's ID attribute. Default empty string.
+ *     @type string[] $additional_classes Optional. A string array of class names. Default empty array.
+ *     @type bool     $paragraph_wrap     Optional. Whether to wrap the message in paragraph tags. Default true.
+ * }
+ */
+function wp_admin_notice( $message, $args = array() ) {
+    /**
+     * Fires before an admin notice is output.
+     *
+     * @since 6.4.0
+     *
+     * @param string $message The message for the admin notice.
+     * @param array  $args    The arguments for the admin notice.
+     */
+    do_action( 'wp_admin_notice', $message, $args );
+
+    echo wp_kses_post( wp_get_admin_notice( $message, $args ) );
+}