Changeset 49123 for trunk/src/wp-admin/includes/dashboard.php

Timestamp:

10/10/2020 08:38:49 PM (4 years ago)

Author:

johnbillion

Message:

Administration: Allow context and priority to be specified when adding dashboard widgets.

Props davidjlaietta, soulseekah, johnbillion

Fixes #42791

File:

• trunk/src/wp-admin/includes/dashboard.php (modified) (5 diffs)

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

@@ -16 +16 @@
  * @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() {
@@ -158 +158 @@
  *
  * @since 2.7.0
- *
- * @global array $wp_dashboard_control_callbacks
+ * @since 5.6.0 The `$context` and `$priority` parameters were added.
+ *
+ * @global callable[] $wp_dashboard_control_callbacks
  *
  * @param string   $widget_id        Widget ID  (used in the 'id' attribute for the widget).
@@ -168 +169 @@
  * @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.
- */
-function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = 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, $context = 'normal', $priority = 'core' ) {
     $screen = get_current_screen();
     global $wp_dashboard_control_callbacks;
@@ -195 +200 @@
     $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 );
 }
 
@@ -1140 +1150 @@
  * @since 2.5.0
  *
- * @global array $wp_dashboard_control_callbacks
+ * @global callable[] $wp_dashboard_control_callbacks
  *
  * @param int $widget_control_id Registered Widget ID.