Validation in WordPress Dashboard Widget API

WordPress Dashboard Widget API is my favorite API in WordPress and sometimes dashboard is my preferred admin page to add simple settings in client site. It’s the screen they will see when they logged in. Why not use it more?

In this post I want to share a little about how to properly save the dashboard meta box “Configuration” with the build in nonce validation.

I read a lot of tutorial but no mention about this, I don’t even find any reference in Codex page.

How to Create Dashboard Widget with Settings?

It’s pretty straight forward. You can read for more detail at The Codex Page.

In this tutorial we are going to create a dashboard widget with a single input configuration option. The option name is  my-dashboard-widget.

Here’s the code:

/* Setup the Dashboard. */
add_action( 'wp_dashboard_setup', 'my_add_dashboard_widget' );

/* Add Dashboard Widget */
function my_add_dashboard_widget(){
    wp_add_dashboard_widget( 'my-dashboard-widget-id', 'My Widget Name', 'my_dashboard_widget_callback', 'my_dashboard_widget_control_callback' );
}

/* Widget HTML Output */
function my_dashboard_widget_callback(){
    ?>
        <p>Your saved input:<br/>
        <?php echo esc_attr( get_option( 'my-dashboard-widget', 'Sorry, no input yet.' ) );?></p>
    <?php
}

/* Widget Configuration */
function my_dashboard_widget_control_callback(){

    /* On form submit, save the input. */
    if( isset( $_POST['my-dashboard-input-name'] ) ){
        update_option( 'my-dashboard-widget', esc_attr( $_POST['my-dashboard-input-name'] ) );
    }
    ?>
    <p>
        <label for="my-dashboard-input">Test Input</label>
    </p>
    <p>
        <input id="my-dashboard-input" class="widefat" name="my-dashboard-input-name" type="text" value="<?php echo esc_attr( get_option( 'my-dashboard-widget' ) );?>"/>
    </p>
    <?php
}

With a very simple code above we have a fully working dashboard widget with options.

But how about nonce?

Nonce and Validation

Actually in every dashboard widget WordPress already have nonce in place. So we don’t need to add the manually in the control callback function. We simply need to use it like so:

if( isset( $_POST['dashboard-widget-nonce'] ) && wp_verify_nonce( $_POST['dashboard-widget-nonce'], 'edit-dashboard-widget_my-dashboard-widget-id' ) ){
    /* Save the option */
}

So the nonce action name is:

edit-dashboard-widget_{widget id}

And the Widget ID is the ID we use in the wp_add_dashboard_widget() function.

So the full code for the control callback function should be:

/* Widget Configuration */
function my_dashboard_widget_control_callback(){

    /* On form submit, save the input. */
    if( isset( $_POST['my-dashboard-input-name'] ) && isset( $_POST['dashboard-widget-nonce'] ) && wp_verify_nonce( $_POST['dashboard-widget-nonce'], 'edit-dashboard-widget_my-dashboard-widget-id' ) ){
        update_option( 'my-dashboard-widget', esc_attr( $_POST['my-dashboard-input-name'] ) );
    }
    ?>
    <p>
        <label for="my-dashboard-input">Test Input</label>
    </p>
    <p>
        <input id="my-dashboard-input" class="widefat" name="my-dashboard-input-name" type="text" value="<?php echo esc_attr( get_option( 'my-dashboard-widget' ) );?>"/>
    </p>
    <?php
}

User Capabilities

Important to remember: To configure the dashboard widgets, a user need to have edit_dashboard capabilities or the “Configure” link will not visible. Of course you can check current user roles/capabilities if you need register and/or save the option based on other caps/role.

I hope this quick tips will help you create dashboard widget faster 😁