Changeset 56408

Timestamp:

08/17/2023 08:27:35 PM (3 years 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 ) );
+}