Ticket #42791: 42791.5.diff

src/wp-admin/includes/dashboard.php

@@ -157 +157 @@
  * 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
  *
@@ -167 +168 @@
  * @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 +199 @@
 
         $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 );
 }
 
 /**

src/wp-admin/includes/template.php

@@ -1014 +1014 @@
  *                                              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.

tests/phpunit/tests/admin/includesTemplate.php

@@ -201 +201 @@
                 );
         }
 
+        /**
+         * @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' );
+        }
+
 }