wp_add_dashboard_widget( string $widget_id, string $widget_name, callable $callback, callable $control_callback = null, array $callback_args = null, string $context = 'normal', string $priority = 'core' )
Adds a new dashboard widget.
Parameters
-
$widget_id
string Required -
Widget ID (used in the
'id'
attribute for the widget). -
$widget_name
string Required -
Title of the widget.
-
$callback
callable Required -
Function that fills the widget with the desired content.
The function should echo its output. -
$control_callback
callable Optional -
Function that outputs controls for the widget.
Default:
null
-
$callback_args
array 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
-
$context
string Optional -
The context within the screen where the box should display.
Accepts'normal'
,'side'
,'column3'
, or'column4'
. Default'normal'
.Default:
'normal'
-
$priority
string Optional -
The priority within the context where the box should show.
Accepts'high'
,'core'
,'default'
, or'low'
. Default'core'
.Default:
'core'
Source
File: wp-admin/includes/dashboard.php
.
View all references
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 );
}
Changelog
Version | Description |
---|---|
5.6.0 | The $context and $priority parameters were added. |
2.7.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Adding dashboard widgets
Here is a simple dashboard widget:
Running dashboard widgets
To run the function use this code:
Adding widgets onto the side
The function doesn’t allow you to choose where you want your widget to go and will automatically add it to the “core” which is the left side. However you are able to get it on the right side very easily.
You can use the
add_meta_box()
function instead ofwp_add_dashboard_widget
. Simply specify ‘dashboard’ in place of the$post_type
. For example:As noted in comment #714,
wp_add_dashboard_widget()
does not offer a great deal of flexibility to position a widget on the dashboard; however, it is possible to add a widget to a specific dashboard column relying onadd_meta_box()
and its$context
parameter.The example below removes all core dashboard widgets and adds a custom one to the third dashboard column (tested ltr only). It looks odd, but it proves the point. 🙃
The doc above states:
$callback_args
(array) (Optional) Data that should be set as the $args property of the widget array (which is the second parameter passed to your callback).
Default value: null
For anyone wondering what the first parameter of that call-back is, it is the current screen object.
If used on the dashboard (which widgets will be), then that parameter returns an empty value.
This is because the dashboard has no screen object.
See also https://wordpress.org/support/topic/what-is-the-first-parameter-passed-to-wp_add_dashboard_widget-callback/
Note that if a plugin implements i18n (internationalization/translation) the $widget_name parameter value needs to be passed to the function using a translation function. Example: