WordPress Version: 5.8
/**
* Adds a new dashboard widget.
*
* @since 2.7.0
* @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).
* @param string $widget_name Title of the widget.
* @param callable $callback Function that fills the widget with the desired content.
* The function should echo its output.
* @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, $context = 'normal', $priority = 'core')
{
global $wp_dashboard_control_callbacks;
$screen = get_current_screen();
$private_callback_args = array('__widget_basename' => $widget_name);
if (is_null($callback_args)) {
$callback_args = $private_callback_args;
} elseif (is_array($callback_args)) {
$callback_args = array_merge($callback_args, $private_callback_args);
}
if ($control_callback && is_callable($control_callback) && current_user_can('edit_dashboard')) {
$wp_dashboard_control_callbacks[$widget_id] = $control_callback;
if (isset($_GET['edit']) && $widget_id === $_GET['edit']) {
list($url) = explode('#', add_query_arg('edit', false), 2);
$widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url($url) . '">' . __('Cancel') . '</a></span>';
$callback = '_wp_dashboard_control_callback';
} else {
list($url) = explode('#', add_query_arg('edit', $widget_id), 2);
$widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url("{$url}#{$widget_id}") . '" class="edit-box open-box">' . __('Configure') . '</a></span>';
}
}
$side_widgets = array('dashboard_quick_press', 'dashboard_primary');
if (in_array($widget_id, $side_widgets, true)) {
$context = 'side';
}
$high_priority_widgets = array('dashboard_browser_nag', 'dashboard_php_nag');
if (in_array($widget_id, $high_priority_widgets, true)) {
$priority = 'high';
}
if (empty($context)) {
$context = 'normal';
}
if (empty($priority)) {
$priority = 'core';
}
add_meta_box($widget_id, $widget_name, $callback, $screen, $context, $priority, $callback_args);
}