WordPress.org

Description

This function adds a new widget to the administration dashboard, using the WordPress Dashboard Widgets API.

Usage

wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback, $callback_args );

Parameters

$widget_id

(string) (required) an identifying slug for your widget. This will be used as the dashboard widget's id attribute, and its key in the array of widgets.

Default: None

$widget_name

(string) (required) this is the name your widget will display in its heading.

Default: None

$callback

(string) (The name of a function you create that will display the actual contents of your widget.) array

Default: None

$control_callback

(string) (optional) The name of a function you create that will handle submission of widget options (configuration) forms, and will also display the form elements.

Default:

$callback_args

(array) (optional) Arguments to pass into your callback function. The callback will receive the $post object and whatever parameters are passed through this variable.

Default:

Examples

Adding Dashboard Widgets

Here is a simple dashboard widget:

// Function that outputs the contents of the dashboard widget
function dashboard_widget_function( $post, $callback_args ) {
	echo "Hello World, this is my first Dashboard Widget!";
}

// Function used in the action hook
function add_dashboard_widgets() {
	wp_add_dashboard_widget('dashboard_widget', 'Example Dashboard Widget', 'dashboard_widget_function');
}

// Register the new dashboard widget with the 'wp_dashboard_setup' action
add_action('wp_dashboard_setup', 'add_dashboard_widgets' );

Running Dashboard Widgets

To run the function use this code:

do_action( 'wp_dashboard_setup' );

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

Using the Control Callback

With the control callback function we can create configurations just like the default feed widgets, WordPress Blog and Other WordPress News.

1) A default message appears asking for the configuration

2) We select a page in the configuration screen

3) The page title and content are shown in the widget

add_action( 'wp_dashboard_setup', 'prefix_add_dashboard_widget' );

function prefix_add_dashboard_widget() {
    wp_add_dashboard_widget(
        'my_dashboard_widget', 
        'Featured Dashboard Page', 
        'prefix_dashboard_widget', 
        'prefix_dashboard_widget_handle'
    );
}

function prefix_dashboard_widget() {
    # get saved data
    if( !$widget_options = get_option( 'my_dashboard_widget_options' ) )
        $widget_options = array( );

    # default output
    $output = sprintf(
        '<h2 style="text-align:right">%s</h2>',
        __( 'Please, configure the widget ☝' )
    );
    
    # check if saved data contains content
    $saved_feature_post = isset( $widget_options['feature_post'] ) 
        ? $widget_options['feature_post'] : false;

    # custom content saved by control callback, modify output
    if( $saved_feature_post ) {
        $post = get_post( $saved_feature_post );
        if( $post ) {
            $content = do_shortcode( html_entity_decode( $post->post_content ) );
            $output = "<h2>{$post->post_title}</h2><p>{$content}</p>";
        }
    }
    echo "<div class='feature_post_class_wrap'>
        <label style='background:#ccc;'>$output</label>
    </div>
    ";
}

function prefix_dashboard_widget_handle()
{
    # get saved data
    if( !$widget_options = get_option( 'my_dashboard_widget_options' ) )
        $widget_options = array( );

    # process update
    if( 'POST' == $_SERVER['REQUEST_METHOD'] && isset( $_POST['my_dashboard_widget_options'] ) ) {
        # minor validation
        $widget_options['feature_post'] = absint( $_POST['my_dashboard_widget_options']['feature_post'] );
        # save update
        update_option( 'my_dashboard_widget_options', $widget_options );
    }

    # set defaults  
    if( !isset( $widget_options['feature_post'] ) )
        $widget_options['feature_post'] = '';


    echo "<p><strong>Available Pages</strong></p>
    <div class='feature_post_class_wrap'>
        <label>Title</label>";
    wp_dropdown_pages( array(
        'post_type'        => 'page',
        'selected'         => $widget_options['feature_post'],
        'name'             => 'my_dashboard_widget_options[feature_post]',
        'id'               => 'feature_post',
        'show_option_none' => '- Select -'
    ) );
    echo "</div>";
}

Change Log

Since: 2.7.0

Source File

wp_add_dashboard_widget() is located in /wp-admin/includes/dashboard.php.

Related

• Dashboard Widgets API
• Function: wp_add_dashboard_widget()
• Function: remove_meta_box()