wp_add_dashboard_widget

Adds a new dashboard widget.

Description

wp_add_dashboard_widget( (string) $widget_id, (string) $widget_name, (callable) $callback, (constant) $control_callback = null, (null) $callback_args = null );

Parameters (5)

0. $widget_id (string): Widget ID (used in the id attribute for the widget).
1. $widget_name (string): Title of the widget.
2. $callback (callable): Function that fills the widget with the desired content. The function should echo its output.
3. $control_callback — Optional. (constant) => null: Function that outputs controls for the widget. Default null.
4. $callback_args — Optional. (null) => null: Data that should be set as the $args property of the widget array (which is the second parameter passed to your callback). Default null.

Usage

if ( !function_exists( 'wp_add_dashboard_widget' ) ) { 
    require_once ABSPATH . '/wp-admin/includes/dashboard.php'; 
} 
  
// Widget ID  (used in the 'id' attribute for the widget). 
$widget_id = ''; 
  
// Title of the widget. 
$widget_name = ''; 
  
// Function that fills the widget with the desired content. 
// The function should echo its output. 
$callback = null; 
  
// Optional. Function that outputs controls for the widget. Default null. 
$control_callback = null; 
  
// 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. 
$callback_args = null; 
  
// NOTICE! Understand what this does before running. 
$result = wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback, $callback_args);

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/dashboard.php

function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null ) { 
    $screen = get_current_screen(); 
    global $wp_dashboard_control_callbacks; 
 
    $private_callback_args = array( '__widget_basename' => $widget_name ); 
 
    if ( is_null( $callback_args ) ) { 
        $callback_args = $private_callback_args; 
    } else if ( is_array( $callback_args ) ) { 
        $callback_args = array_merge( $callback_args, $private_callback_args ); 
    } 
 
    if ( $control_callback && current_user_can( 'edit_dashboard' ) && is_callable( $control_callback ) ) { 
        $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' ); 
 
    $location = 'normal'; 
    if ( in_array($widget_id, $side_widgets) ) 
        $location = 'side'; 
 
    $priority = 'core'; 
    if ( 'dashboard_browser_nag' === $widget_id ) 
        $priority = 'high'; 
 
    add_meta_box( $widget_id, $widget_name, $callback, $screen, $location, $priority, $callback_args ); 
}