Using WordPress ‘add_dashboard_page()’ PHP function

by

The add_dashboard_page() WordPress PHP function is used to add a submenu page to the Dashboard main menu. This function takes into consideration a user’s capability, which determines if the page is included in the menu. It also requires the hooked function to check if the user has the necessary capability.

Usage

Here’s a simplified example of how to use the function:

add_dashboard_page('My Custom Dashboard', 'Custom Dashboard', 'read', 'my-custom-dashboard', 'my_custom_dashboard_output');

In this example, ‘My Custom Dashboard’ is the title of the page, ‘Custom Dashboard’ is the menu title, ‘read’ is the capability required, ‘my-custom-dashboard’ is the unique menu slug, and ‘my_custom_dashboard_output’ is the function to output the content.

Parameters

  • $page_title (string) – The text to be displayed in the title tags of the page when the menu is selected.
  • $menu_title (string) – The text to be used for the menu.
  • $capability (string) – The capability required for this menu to be displayed to the user.
  • $menu_slug (string) – The unique slug name to refer to this menu.
  • $callback (callable, optional) – The function to be called to output the content for this page. Default: ”
  • $position (int, optional) – The position in the menu order this item should appear. Default: null

More information

See WordPress Developer Resources: add_dashboard_page()

The function is typically used in a function registered with the ‘admin_menu’ hook.

Examples

Custom Dashboard Page

This example adds a new page to the dashboard menu called ‘My Custom Dashboard’. The ‘my_custom_dashboard_output’ function will handle the output of the page content.

function my_plugin_menu() {
    add_dashboard_page('My Custom Dashboard', 'Custom Dashboard', 'read', 'my-custom-dashboard', 'my_custom_dashboard_output');
}
add_action('admin_menu', 'my_plugin_menu');

function my_custom_dashboard_output() {
    echo 'Welcome to My Custom Dashboard!';
}

In this code, we’ve first defined the function my_plugin_menu(). Inside this function, we call add_dashboard_page() to add a new page to the dashboard. The last line hooks our my_plugin_menu() function into WordPress using the admin_menu hook.

The my_custom_dashboard_output() function is where you define what will be displayed on your new dashboard page. In this case, it simply outputs a welcome message.

Custom Dashboard Page with Position

This example is similar to the first, but it specifies the position of the new page in the dashboard menu.

function my_plugin_menu() {
    add_dashboard_page('My Custom Dashboard', 'Custom Dashboard', 'read', 'my-custom-dashboard', 'my_custom_dashboard_output', 3);
}
add_action('admin_menu', 'my_plugin_menu');

function my_custom_dashboard_output() {
    echo 'Welcome to My Custom Dashboard!';
}

In this code, the new dashboard page will appear at position 3 in the menu.

Custom Dashboard Page for Editors

This example creates a new dashboard page that only users with the ‘edit_posts’ capability can see.

function my_plugin_menu() {
    add_dashboard_page('My Custom Dashboard', 'Custom Dashboard', 'edit_posts', 'my-custom-dashboard', 'my_custom_dashboard_output');
}
add_action('admin_menu', 'my_plugin_menu');

function my_custom_dashboard_output() {
    echo 'Welcome to My Custom Dashboard!';
}