Make WordPress Core

Changeset 56408


Ignore:
Timestamp:
08/17/2023 08:27:35 PM (11 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:
2 added
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/misc.php

    r56144 r56408  
    16431643    return $response;
    16441644}
     1645
     1646/**
     1647 * Creates and returns the markup for an admin notice.
     1648 *
     1649 * @since 6.4.0
     1650 *
     1651 * @param string $message The message.
     1652 * @param array  $args {
     1653 *     Optional. An array of arguments for the admin notice. Default empty array.
     1654 *
     1655 *     @type string   $type               Optional. The type of admin notice.
     1656 *                                        For example, 'error', 'success', 'warning', 'info'.
     1657 *                                        Default empty string.
     1658 *     @type bool     $dismissible        Optional. Whether the admin notice is dismissible. Default false.
     1659 *     @type string   $id                 Optional. The value of the admin notice's ID attribute. Default empty string.
     1660 *     @type string[] $additional_classes Optional. A string array of class names. Default empty array.
     1661 *     @type bool     $paragraph_wrap     Optional. Whether to wrap the message in paragraph tags. Default true.
     1662 * }
     1663 * @return string The markup for an admin notice.
     1664 */
     1665function wp_get_admin_notice( $message, $args = array() ) {
     1666    $defaults = array(
     1667        'type'               => '',
     1668        'dismissible'        => false,
     1669        'id'                 => '',
     1670        'additional_classes' => array(),
     1671        'paragraph_wrap'     => true,
     1672    );
     1673
     1674    $args = wp_parse_args( $args, $defaults );
     1675
     1676    /**
     1677     * Filters the arguments for an admin notice.
     1678     *
     1679     * @since 6.4.0
     1680     *
     1681     * @param array  $args    The arguments for the admin notice.
     1682     * @param string $message The message for the admin notice.
     1683     */
     1684    $args    = apply_filters( 'wp_admin_notice_args', $args, $message );
     1685    $id      = '';
     1686    $classes = 'notice';
     1687
     1688    if ( is_string( $args['id'] ) ) {
     1689        $trimmed_id = trim( $args['id'] );
     1690
     1691        if ( '' !== $trimmed_id ) {
     1692            $id = 'id="' . $trimmed_id . '" ';
     1693        }
     1694    }
     1695
     1696    if ( is_string( $args['type'] ) ) {
     1697        $type = trim( $args['type'] );
     1698
     1699        if ( str_contains( $type, ' ' ) ) {
     1700            _doing_it_wrong(
     1701                __FUNCTION__,
     1702                sprintf(
     1703                    /* translators: %s: The "type" key. */
     1704                    __( 'The %s key must be a string without spaces.' ),
     1705                    '<code>type</code>'
     1706                ),
     1707                '6.4.0'
     1708            );
     1709        }
     1710
     1711        if ( '' !== $type ) {
     1712            $classes .= ' notice-' . $type;
     1713        }
     1714    }
     1715
     1716    if ( true === $args['dismissible'] ) {
     1717        $classes .= ' is-dismissible';
     1718    }
     1719
     1720    if ( is_array( $args['additional_classes'] ) && ! empty( $args['additional_classes'] ) ) {
     1721        $classes .= ' ' . implode( ' ', $args['additional_classes'] );
     1722    }
     1723
     1724    if ( false !== $args['paragraph_wrap'] ) {
     1725        $message = "<p>$message</p>";
     1726    }
     1727
     1728    $markup = sprintf( '<div %1$sclass="%2$s">%3$s</div>', $id, $classes, $message );
     1729
     1730    /**
     1731     * Filters the markup for an admin notice.
     1732     *
     1733     * @since 6.4.0
     1734     *
     1735     * @param string $markup  The HTML markup for the admin notice.
     1736     * @param string $message The message for the admin notice.
     1737     * @param array  $args    The arguments for the admin notice.
     1738     */
     1739    return apply_filters( 'wp_admin_notice_markup', $markup, $message, $args );
     1740}
     1741
     1742/**
     1743 * Outputs an admin notice.
     1744 *
     1745 * @since 6.4.0
     1746 *
     1747 * @param string $message The message to output.
     1748 * @param array  $args {
     1749 *     Optional. An array of arguments for the admin notice. Default empty array.
     1750 *
     1751 *     @type string   $type               Optional. The type of admin notice.
     1752 *                                        For example, 'error', 'success', 'warning', 'info'.
     1753 *                                        Default empty string.
     1754 *     @type bool     $dismissible        Optional. Whether the admin notice is dismissible. Default false.
     1755 *     @type string   $id                 Optional. The value of the admin notice's ID attribute. Default empty string.
     1756 *     @type string[] $additional_classes Optional. A string array of class names. Default empty array.
     1757 *     @type bool     $paragraph_wrap     Optional. Whether to wrap the message in paragraph tags. Default true.
     1758 * }
     1759 */
     1760function wp_admin_notice( $message, $args = array() ) {
     1761    /**
     1762     * Fires before an admin notice is output.
     1763     *
     1764     * @since 6.4.0
     1765     *
     1766     * @param string $message The message for the admin notice.
     1767     * @param array  $args    The arguments for the admin notice.
     1768     */
     1769    do_action( 'wp_admin_notice', $message, $args );
     1770
     1771    echo wp_kses_post( wp_get_admin_notice( $message, $args ) );
     1772}
Note: See TracChangeset for help on using the changeset viewer.