WordPress Custom Dashboard Widgets

/ Blog, WordPress, WordPress Development /

Dashboard widgets have been introduced in WordPress since version 2.7. In this article, we are going to discuss how to create custom dashboard widgets. Dashboard widgets are widgets that you see when you enter the admin section on the Dashboard page. One of these widgets is Quick Draft, which is included by default in WordPress, and we can easily create a draft of a post without going to the posts menu and creating a post in this section.

In this tutorial, we will introduce and create a dashboard widget and we will examine examples of displaying and receiving data through the form in these widgets. So stay with us.

Create WordPress dashboard widgets

To create dashboard widgets in WordPress, you must have basic knowledge of HTML, CSS, PHP, and WordPress development. You should also know how hooks work in WordPress. If you do not have information in this field, we have prepared tutorials for you on this website.

To create a dashboard widget, we use the wp_add_dashboard_widget function.

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

This function adds a new widget in the WordPress dashboard. The input parameters of this function are described below.

  • widget_id: Widget ID (used in the 'id' attribute for the widget). an identifying slug for your widget. This will be used as its CSS class and its key in the array of widgets.
  • widget_name: This is the name your widget will display in its heading.
  • Callback: Function that fills the widget with the desired content. The function should echo its output. The name of a function you will create that will display the actual contents of your widget.
  • control_callback: Function that outputs controls for the widget. The name of a function you create that will handle submission of widget options forms, and will also display the form elements.
  • callback_args: Data that should be set as the $args property of the widget array (which is the second parameter passed to your callback).
  • Context: The context within the screen where the box should display. Accepts 'normal', 'side', 'column3', or 'column4'. Default 'normal'.
  • Priority: The priority within the context where the box should show. Accepts 'high', 'core', 'default', or 'low'. Default 'core'.

To execute the function, you must use the action hook wp_dashboard_setup and the add_action() function. Also, use the wp_network_dashboard_setup hook for the network management dashboard.

For example, open the functions.php file of your WordPress theme and add the following codes to the end of it.

function hs_add_dashboard_widgets() {
    wp_add_dashboard_widget( 
        'hs_dashboard_widget', 
        esc_html__( 'Simple Dashboard Widget', 'textdomain' ), 
        'hs_dashboard_widget_function' 
    );

    function hs_dashboard_widget_function(){
        ?>
        <p>This is a Dashboard Widget.</p>
        <?php
    }
}
add_action( 'wp_dashboard_setup', 'hs_add_dashboard_widgets' );

This is a simple example of how to create a dashboard widget in WordPress that displays a message on the WordPress dashboard for the trustee.

WordPress Dashboard widgets

In this example, we send three parameters to the wp_add_dashnoard_widget hook. The first parameter is the ID of the widget, the second parameter is the title of the widget, and the third parameter is the name of the widget content display function.

Forcing your widget to the top

In the previous example, the dashboard widget was added, it is placed last, that is, at the end of the WordPress dashboard page. In this section, we want to bring this widget to the top of the page. This work is not possible easily and only by entering a higher number in the priority, and we need to make changes in the WordPress metaboxes so that we can place the widget at the top of the display list.

function hs_add_dashboard_widgets() {
    wp_add_dashboard_widget( 
        'hs_dashboard_widget', 
        esc_html__( 'Simple Dashboard Widget', 'textdomain' ), 
        'hs_dashboard_widget_function' 
    );

    function hs_dashboard_widget_function(){
        ?>
        <p>This is a Dashboard Widget.</p>
        <?php
    }

    global $wp_meta_boxes;
    
    $default_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];
    $example_widget_backup = array( 'hs_dashboard_widget' => $default_dashboard['hs_dashboard_widget'] );
    unset( $default_dashboard['hs_dashboard_widget'] );
     $sorted_dashboard = array_merge( $example_widget_backup, $default_dashboard );

    $wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
}
add_action( 'wp_dashboard_setup', 'hs_add_dashboard_widgets' );

Of course, this method does not do this completely because if there is already a widget that has used this method, that widget may be displayed before our widget. Also, this method only works for people who have never sorted their widgets. If the user has sorted his dashboard widgets, WordPress will replace the user’s sorting with the default sorting. In this case, the user should bring our widget to the top of the page.

Removing default Dashboard Widgets

If you are tired of your dashboard widgets and don’t want them to be displayed on the dashboard, WordPress has a solution for this. The first method is to remove them from the “Screen Options” menu at the top of the screen. But if you want to get rid of them forever, you can easily remove the default WordPress widgets from the dashboard by using the remove_meta_box() function.

global $wp_meta_boxes;
// Main column (left): 
// Browser Update Required
$wp_meta_boxes['dashboard']['normal']['high']['dashboard_browser_nag']; 
// PHP Update Required
$wp_meta_boxes['dashboard']['normal']['high']['dashboard_php_nag']; 

// At a Glance
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now'];
// Right Now
$wp_meta_boxes['dashboard']['normal']['core']['network_dashboard_right_now'];
// Activity
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_activity'];
// Site Health Status
$wp_meta_boxes['dashboard']['normal']['core']['health_check_status'];

// Side Column (right): 
// WordPress Events and News
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary'];
// Quick Draft, Your Recent Drafts
$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press'];

Or we can do the following.

remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
remove_meta_box( 'dashboard_browser_nag', 'dashboard', 'normal' );
remove_meta_box( 'dashboard_php_nag', 'dashboard', 'normal' );
remove_meta_box( 'dashboard_right_now', 'dashboard', 'normal' );
remove_meta_box( 'network_dashboard_right_now', 'dashboard', 'normal' );
remove_meta_box( 'dashboard_activity', 'dashboard', 'normal' );
remove_meta_box( 'health_check_status', 'dashboard', 'normal' );
remove_meta_box( 'dashboard_primary', 'dashboard', 'side' );

Even if we want to delete one of the dashboard widgets that is not the default widget and is created by a theme or plugin, it is enough to know its id. For example, we delete one of the bbPress plugin widgets with the following code.

unset($wp_meta_boxes['dashboard']['normal']['core']['bbp-dashboard-right-now']);

Examples of WordPress dashboard widgets

Now that we are familiar with how to add a dashboard widget to the WordPress dashboard page and how to display information inside it, we will review some examples.

Displaying a feed

In this example, we extract website feeds using the wp_dashboard_primary_output hook.

function hs_add_dashboard_widgets() {
    wp_add_dashboard_widget( 
        'hs_dashboard_widget', 
        esc_html__( 'Simple Dashboard Widget', 'textdomain' ), 
        'hs_dashboard_widget_function' 
    );

    function hs_dashboard_widget_function(){
        $feeds = array(
            array(
                'url'          => 'https://www.honarsystems.com/feed/',
                'items'        => 5,
                'show_summary' => 1,
                'show_author'  => 0,
                'show_date'    => 1,
            ),
        );
    
        wp_dashboard_primary_output( 'dw_dashboard_widget_news', $feeds );
    }
}
add_action( 'wp_dashboard_setup', 'hs_add_dashboard_widgets' );

This example extracts 5 of the honarsystems.com website feeds and displays them inside the widget. You can use this method to extract the feeds of your favorite website. For this, just change the website address to your desired address.

Email sender

Using this widget, you can send emails from within the WordPress dashboard widget.

function hs_add_dashboard_widgets() {
    wp_add_dashboard_widget( 
        'hs_dashboard_widget', 
        esc_html__( 'Simple Dashboard Widget', 'textdomain' ), 
        'hs_dashboard_widget_function' 
    );

    function hs_dashboard_widget_function(){
        if ($_SERVER['REQUEST_METHOD'] == 'POST') {
            $to = $_POST['hs-email'];
            $subject = $_POST['hs-subject'];
            $body = $_POST['hs-message'];
            $headers = array('Content-Type: text/html; charset=UTF-8');

            wp_mail( $to, $subject, $body, $headers );
        }

        ?>
        <form method="post" action="<?php echo $_SERVER['PHP_SELF']; ?>">
            <label for="hs-email"><?php esc_html_e("Email","textdomain"); ?></label>
            <input type="email" name="hs-email" class="widefat" placeholder="<?php esc_html_e("Email","textdomain"); ?>" />
            <label for="hs-subject"><?php esc_html_e("Subject","textdomain"); ?></label>
            <input type="text" name="hs-subject" class="widefat" placeholder="<?php esc_html_e("Subject","textdomain"); ?>" />
            <label for="hs-message"><?php esc_html_e("Message","textdomain"); ?></label>
            <textarea name="hs-message" rows="7" placeholder="<?php esc_html_e("Message","textdomain"); ?>" class="widefat"></textarea>
            <input type="submit" value="<?php esc_html_e("Send","textdomain"); ?>" class="button button-primary" />
        </form>
        <?php
    }
}
add_action( 'wp_dashboard_setup', 'hs_add_dashboard_widgets' );

In this example, we send an email using the wp_mail function to the email entered through WordPress. To work with forms in WordPress, we can also use AJAX, which we have explained in an article entitled “How to work with AJAX in WordPress“.

Related Posts

Shopping Cart