diff --git a/src/wp-admin/includes/dashboard.php b/src/wp-admin/includes/dashboard.php index 7ed08b8119..b36ef18dce 100644 --- a/src/wp-admin/includes/dashboard.php +++ b/src/wp-admin/includes/dashboard.php @@ -15,7 +15,7 @@ * * @global array $wp_registered_widgets * @global array $wp_registered_widget_controls - * @global array $wp_dashboard_control_callbacks + * @global callable[] $wp_dashboard_control_callbacks */ function wp_dashboard_setup() { global $wp_registered_widgets, $wp_registered_widget_controls, $wp_dashboard_control_callbacks; @@ -157,8 +157,9 @@ function wp_dashboard_setup() { * Adds a new dashboard widget. * * @since 2.7.0 + * @since 5.6.0 The `$context` and `$priority` parameters were added. * - * @global array $wp_dashboard_control_callbacks + * @global callable[] $wp_dashboard_control_callbacks * * @param string $widget_id Widget ID (used in the 'id' attribute for the widget). * @param string $widget_name Title of the widget. @@ -167,8 +168,12 @@ function wp_dashboard_setup() { * @param callable $control_callback Optional. Function that outputs controls for the widget. Default null. * @param array $callback_args Optional. Data that should be set as the $args property of the widget array * (which is the second parameter passed to your callback). Default null. + * @param string $context Optional. The context within the screen where the box should display. + * Accepts 'normal', 'side', 'column3', or 'column4'. Default 'normal'. + * @param string $priority Optional. The priority within the context where the box should show. + * Accepts 'high', 'core', 'default', or 'low'. Default 'core'. */ -function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null ) { +function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null, $context = 'normal', $priority = 'core' ) { $screen = get_current_screen(); global $wp_dashboard_control_callbacks; @@ -194,19 +199,24 @@ function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_ $side_widgets = array( 'dashboard_quick_press', 'dashboard_primary' ); - $location = 'normal'; if ( in_array( $widget_id, $side_widgets, true ) ) { - $location = 'side'; + $context = 'side'; } $high_priority_widgets = array( 'dashboard_browser_nag', 'dashboard_php_nag' ); - $priority = 'core'; if ( in_array( $widget_id, $high_priority_widgets, true ) ) { $priority = 'high'; } - add_meta_box( $widget_id, $widget_name, $callback, $screen, $location, $priority, $callback_args ); + if ( empty( $context ) ) { + $context = 'normal'; + } + if ( empty( $priority ) ) { + $priority = 'core'; + } + + add_meta_box( $widget_id, $widget_name, $callback, $screen, $context, $priority, $callback_args ); } /** @@ -1139,7 +1149,7 @@ function wp_dashboard_cached_rss_widget( $widget_id, $callback, $check_urls = ar * * @since 2.5.0 * - * @global array $wp_dashboard_control_callbacks + * @global callable[] $wp_dashboard_control_callbacks * * @param int $widget_control_id Registered Widget ID. */ diff --git a/src/wp-admin/includes/template.php b/src/wp-admin/includes/template.php index d27a7d6f79..aa27e6a527 100644 --- a/src/wp-admin/includes/template.php +++ b/src/wp-admin/includes/template.php @@ -1014,14 +1014,14 @@ function wp_import_upload_form( $action ) { * add_submenu_page() to create a new screen (and hence screen_id), * make sure your menu slug conforms to the limits of sanitize_key() * otherwise the 'screen' menu may not correctly render on your page. - * @param string $context Optional. The context within the screen where the boxes + * @param string $context Optional. The context within the screen where the box * should display. Available contexts vary from screen to * screen. Post edit screen contexts include 'normal', 'side', * and 'advanced'. Comments screen contexts include 'normal' * and 'side'. Menus meta boxes (accordion sections) all use * the 'side' context. Global default is 'advanced'. - * @param string $priority Optional. The priority within the context where the boxes - * should show ('high', 'low'). Default 'default'. + * @param string $priority Optional. The priority within the context where the box should show. + * Accepts 'high', 'core', 'default', or 'low'. Default 'default'. * @param array $callback_args Optional. Data that should be set as the $args property * of the box array (which is the second parameter passed * to your callback). Default null. diff --git a/tests/phpunit/tests/admin/includesTemplate.php b/tests/phpunit/tests/admin/includesTemplate.php index 80a74eb4ef..bb2ba4070d 100644 --- a/tests/phpunit/tests/admin/includesTemplate.php +++ b/tests/phpunit/tests/admin/includesTemplate.php @@ -201,4 +201,41 @@ class Tests_Admin_includesTemplate extends WP_UnitTestCase { ); } + /** + * @ticket 42791 + */ + public function test_wp_add_dashboard_widget() { + global $wp_meta_boxes; + + set_current_screen( 'dashboard' ); + + if ( ! function_exists( 'wp_add_dashboard_widget' ) ) { + require_once ABSPATH . 'wp-admin/includes/dashboard.php'; + } + + // Some hardcoded defaults for core widgets + wp_add_dashboard_widget( 'dashboard_quick_press', 'Quick', '__return_false' ); + wp_add_dashboard_widget( 'dashboard_browser_nag', 'Nag', '__return_false' ); + + $this->assertArrayHasKey( 'dashboard_quick_press', $wp_meta_boxes['dashboard']['side']['core'] ); + $this->assertArrayHasKey( 'dashboard_browser_nag', $wp_meta_boxes['dashboard']['normal']['high'] ); + + // Location and priority defaults + wp_add_dashboard_widget( 'dashboard1', 'Widget 1', '__return_false', null, null, 'foo' ); + wp_add_dashboard_widget( 'dashboard2', 'Widget 2', '__return_false', null, null, null, 'bar' ); + + $this->assertArrayHasKey( 'dashboard1', $wp_meta_boxes['dashboard']['foo']['core'] ); + $this->assertArrayHasKey( 'dashboard2', $wp_meta_boxes['dashboard']['normal']['bar'] ); + + // Cleanup + remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' ); + remove_meta_box( 'dashboard_browser_nag', 'dashboard', 'normal' ); + remove_meta_box( 'dashboard1', 'dashboard', 'foo' ); + + // This doesn't actually get removed due to the invalid priority + remove_meta_box( 'dashboard2', 'dashboard', 'normal' ); + + set_current_screen( 'front' ); + } + }