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.

Contents

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'

Top ↑

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 );
}

View on Trac View on GitHub

Top ↑

Top ↑

Uses

Uses
Uses Description
get_current_screen() wp-admin/includes/screen.php

Get the current screen object
add_meta_box() wp-admin/includes/template.php

Adds a meta box to one or more screens.
current_user_can() wp-includes/capabilities.php

Returns whether the current user has the specified capability.
__() wp-includes/l10n.php

Retrieves the translation of $text.
esc_url() wp-includes/formatting.php

Checks and cleans a URL.
add_query_arg() wp-includes/functions.php

Retrieves a modified URL query string.
Show 4 more uses Hide more uses

Top ↑

Changelog

Changelog
Version Description
5.6.0 The $context and $priority parameters were added.
2.7.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Adding dashboard widgets
    Here is a simple dashboard widget:

    /**
 * Add a new dashboard widget.
 */
function wpdocs_add_dashboard_widgets() {
	wp_add_dashboard_widget( 'dashboard_widget', 'Example Dashboard Widget', 'dashboard_widget_function' );
}
add_action( 'wp_dashboard_setup', 'wpdocs_add_dashboard_widgets' );

/**
 * Output the contents of the dashboard widget
 */
function dashboard_widget_function( $post, $callback_args ) {
	esc_html_e( "Hello World, this is my first Dashboard Widget!", "textdomain" );
}
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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 of wp_add_dashboard_widget. Simply specify ‘dashboard’ in place of the $post_type. For example:

    add_meta_box( 'id', 'Dashboard Widget Title', 'dash_widget', 'dashboard', 'side', 'high' );
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Caspar Hübinger —

    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 on add_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. 🙃

    <?php
namespace Exampledashboard;

add_action( 'wp_dashboard_setup', __NAMESPACE__ . 'wp_dashboard_setup' );

/**
 * Remove core widhets and add widget to Dashboard in third column.
 * @see https://developer.wordpress.org/reference/functions/add_meta_box/
 */
function wp_dashboard_setup() {

	// Remove Welcome panel.
	remove_action( 'welcome_panel', 'wp_welcome_panel' );

	// Remove all Dashboard widgets.
	global $wp_meta_boxes;
	unset( $wp_meta_boxes['dashboard'] );

	// Add custom dashbboard widget.
	add_meta_box( 'dashboard_widget_example',
		__( 'Example Widget', 'example-text-domain' ),
		__NAMESPACE__ . 'render_example_widget',
		'dashboard',
		'column3',  // $context: 'advanced', 'normal', 'side', 'column3', 'column4'
		'high',     // $priority: 'high', 'core', 'default', 'low'
	);
}

/**
 * Render widget.
 */
function render_example_widget() {
?>
	<p>Do something.</p>
<?php
}
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Beda —

    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/

  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by nlpro —

    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:

    wp_add_dashboard_widget( $widget_id, __( 'This is a translated widget title', 'example-plugin' ), … );

You must log in before being able to contribute a note or feedback.