How To Create A WordPress Custom Dashboard Page

A few days ago, i have been asked to create a custom WordPress dashboard to replace the orginial one. It wasn’t just displaying or hiding already custom metaboxes, it was replacing the whole dashboard. This was the first time i was asked to do something like that, so it was pretty challenging. As always, in this case, i looked over the internet to see if something similar had already been done. and once again, no result. I don’t know if i’m bad in asking Google specific stuff, or if most WordPress tutorials treat about the same subjects, but i coudn’t find anything.
Then, i remember, that since WordPress 3.x, there’s a new page once we login for the first time after an update. This is more or less what i wanted to do.
After a quick search in WordPress core files, i found really great stuff. And finally, i managed to create a whole custom dashboard in the WordPress style. To do so, once again i created a plugin.

Step 1: the plugin creation

If you read my previous posts on WPexplorer you should now know about to create a plugin, but here is a reminder.
Open the plugins folder under wp-content, and create a new repository called «sweet-custom-dashboard», and inside this folder create a new file called «sweet-custom-dashboard.php». Then open the file.
To declare the plugin, simply add this code to the file:

<?php
/*
Plugin Name: Sweet Custom Dashboard
Plugin URL: http://remicorson.com/sweet-custom-dashboard Description: A nice plugin to create your custom dashboard page
Version: 0.1
Author: Remi Corson
Author URI: http://remicorson.com Contributors: corsonr
Text Domain: rc_scd
*/

Only by adding this code, you already created a plugin, an empty plugin, but a working plugin!
Now, we need to define a constant for the plugin URL, we’ll need later. Add this code:

/*
|--------------------------------------------------------------------------
| CONSTANTS
|--------------------------------------------------------------------------
*/
// plugin folder url
if(!defined('RC_SCD_PLUGIN_URL')) {
define('RC_SCD_PLUGIN_URL', plugin_dir_url( __FILE__ ));
}

It’s now time to create the main class of our plugin:

/*
|--------------------------------------------------------------------------
| MAIN CLASS
|--------------------------------------------------------------------------
*/

class rc_sweet_custom_dashboard {

 /*--------------------------------------------*
  * Constructor
  *--------------------------------------------*/

 /**
  * Initializes the plugin
  */
 function __construct() {

 } // end constructor

}

// instantiate plugin's class
$GLOBALS['sweet_custom_dashboard'] = new rc_sweet_custom_dashboard();

Step 2: The constructor

In step two, we need to add an action that will occur only if the user is on the dashboard page. To do so, replace the constructore function by this code:

function __construct() {

 add_action('admin_menu', array( &$this,'rc_scd_register_menu') );
 add_action('load-index.php', array( &$this,'rc_scd_redirect_dashboard') );

} // end constructor

By adding this code, we’re telling WordPress that we want to load the rc_get_screen() function when index.php is loaded (index.php is the dashboard page). We are also telling WordPress to register a new dashboard page. The one we’ll use in the redirection. Next step is the construction of the rc_redirect_dashboard() function.

Step 3: the dashboard redirection

The rc_redirect_dashboard() function is pretty simple. Its aim is to redirect the user to a custom page when he wants to access the default dashboard. To do this, we have to check if we are on the right screen (read «page») using the get_current_screen() function. When this function called from the ‘admin_init’ hook it returns NULL, that’s in part why i hooked the rc_dashboard_redirection() to «load-index.php». Here is the function’s content:

function rc_scd_redirect_dashboard() {

 if( is_admin() ) {
  $screen = get_current_screen();
  
  if( $screen->base == 'dashboard' ) {

   wp_redirect( admin_url( 'index.php?page=custom-dashboard' ) );
   
  }
 }

}

This code is prtty understandable, if we are in the admin, and if the current screen is «dashboard» then we force a redirection to a file called «custom_dashboard.php».

Registering the dashboard page

It’s now time to register the new dashboard page. To do this, we need to add two functions: one to register the page in the WordPress menu and one to fill in the content page:

function rc_scd_register_menu() {
 add_dashboard_page( 'Custom Dashboard', 'Custom Dashboard', 'read', 'custom-dashboard', array( &$this,'rc_scd_create_dashboard') );
}

function rc_scd_create_dashboard() {
 include_once( 'custom_dashboard.php'  );
}

If you saved the file, activate the plugin and try to access the dashboard, you should see a blank page or a 404 message. We can create our custom dashboard.

Step 4: The custom dashboard creation

When i created this plugin, i wanted the new dashboard to be in the WordPress style, that’s why my starting point was, the page that you see when you login for the first time afte a core update. I went through the code of this page to find inspiration.
To start, create a new file called «custom_dashboard.php» in your sweet-custom-dashboard folder. Open it and add this code:

<?php
/**
 * Our custom dashboard page
 */

/** WordPress Administration Bootstrap */
require_once( ABSPATH . 'wp-load.php' );
require_once( ABSPATH . 'wp-admin/admin.php' );
require_once( ABSPATH . 'wp-admin/admin-header.php' );
?>

The first require_once() fucntion, loads WordPress, by adding this simple line, you are now able to use any WordPress variables or any functions.
The two other require_once() load needed filed to display properly the administration.
All we have to now is to create the content of our custom dashboard. The code below is inspired by the file mentioned previously that’s why you’ll maybe need to adjust it a bit to fit your needs. In my example i just want a menu with 3 links that will be displayed as tabs, and two paragraphs, once including an image. Here is the code:

<div class="wrap about-wrap">
<h1><?php _e( 'Welcome to My Custom Dashboard Page' ); ?></h1>

 <div class="about-text">
 <?php _e('Donec id elit non mi porta gravida at eget metus. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.' ); ?>
 </div>

 <h2 class="nav-tab-wrapper">
 <a href="#" class="nav-tab nav-tab-active">
 <?php _e( 'Step 1' ); ?>
 </a><a href="#" class="nav-tab">
 <?php _e( 'Step 2' ); ?>
 </a><a href="#" class="nav-tab">
 <?php _e( 'Step 3' ); ?>
 </a>
 </h2>

 <div class="changelog">
 <h3><?php _e( 'Morbi leo risus, porta ac consectetur' ); ?></h3>

 <div class="feature-section images-stagger-right">
 <img src="<?php echo esc_url( admin_url( 'images/screenshots/theme-customizer.png' ) ); ?>" class="image-50" />
 <h4><?php _e( 'Risus Consectetur Elit Sollicitudin' ); ?></h4>
 <p><?php _e( 'Cras mattis consectetur purus sit amet fermentum. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Vestibulum id ligula porta felis euismod semper. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Nulla vitae elit libero, a pharetra augue. Donec sed odio dui.' ); ?></p>

 <h4><?php _e( 'Mattis Justo Purus' ); ?></h4>
 <p><?php _e( 'Aenean lacinia bibendum nulla sed consectetur. Donec id elit non mi porta gravida at eget metus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum id ligula porta felis euismod semper. Integer posuere erat a ante venenatis dapibus posuere velit aliquet.
Cras mattis consectetur purus sit amet fermentum. Maecenas faucibus mollis interdum. Etiam porta sem malesuada magna mollis euismod. Maecenas faucibus mollis interdum. Curabitur blandit tempus porttitor. Cras justo odio, dapibus ac facilisis in, egestas eget quam.' ); ?></p>
 </div>
 </div>
</div>

Nothing really interesting in this code, it’s just HTML code.
And finally, we have to load the WordPress administration footer. To do so, just this line at the bottom of the file:

<?php include( ABSPATH . 'wp-admin/admin-footer.php' );

And… that’s it ! The plugin is now working great, there’s of course many many ways to make it better, for example you could add custom stylesheets and custom javascript files, or you could add some extra verification to display the custom dashboard to some user roles only…
Well, i hope you enjoyed this tutorial, and i am looking forward to read your comments in the comments section!
One more thing, there’s an already compiled version of the plugin on the official WordPress plugins repositoryn click here to download it.