Adding a subpage to the WordPress admin menu with add_submenu_page

The WordPress add_submenu_page function is used to add a new submenu page to an existing top-level menu in the WordPress admin dashboard. This function can be useful for organizing and categorizing related settings or functionality under a specific top-level menu. It allows developers to create a clear and structured navigation for users within the admin dashboard, making it easier for them to find and access the desired functionality or settings.

  • It helps in improving the user experience by grouping related options or features together.
  • It allows for better organization and navigation within the WordPress admin dashboard.
  • It provides a way to extend the functionality of existing top-level menus by adding additional submenus.

The add_submenu_page function is a valuable tool for developers to enhance the usability and organization of their WordPress plugins or themes within the admin dashboard.

Parameters Accepted by add_submenu_page Function

The add_submenu_page function accepts the following parameters:

  • $parent_slug (string, required): The slug name for the parent menu (or the file name of a standard WordPress admin page).
  • $page_title (string, required): The text to be displayed in the title tags of the page when the menu is selected.
  • $menu_title (string, required): The text to be used for the menu.
  • $capability (string, required): The capability required for this menu to be displayed to the user.
  • $menu_slug (string, required): The slug name to refer to this menu by. Should be unique for this menu and only include lowercase alphanumeric, dashes, and underscores characters to be compatible with sanitize_key().
  • $callback (callable, optional, default value: ”): The function to be called to output the content for this page.
  • $position (int/float, optional, default value: null): The position in the menu order this item should appear.

Value Returned by add_submenu_page Function

The add_submenu_page function returns a string representing the resulting page’s hook_suffix, or false if the user does not have the capability required.

Examples

How to add a submenu page in WordPress

Here’s a basic example of using the add_submenu_page function to add a submenu page in WordPress:

add_action('admin_menu', 'my_custom_menu');

function my_custom_menu() {
 add_menu_page('Custom Menu', 'Custom Menu', 'manage_options', 'my-top-level-handle', 'my_custom_menu_page', 'dashicons-admin-generic', 6);
 add_submenu_page('my-top-level-handle', 'Submenu Page', 'Submenu Page', 'manage_options', 'my-secondary-handle', 'my_secondary_menu_page');
}

function my_custom_menu_page() {
 // Content for the custom menu page
}

function my_secondary_menu_page() {
 // Content for the submenu page
}

This code adds a custom top-level menu page and a submenu page in the WordPress admin menu. The add_submenu_page function is used to add the submenu page under the custom top-level menu.

How to add a submenu page with a callback function in WordPress

Here’s an example of using the add_submenu_page function with a callback function to add a submenu page in WordPress:

add_action('admin_menu', 'my_custom_menu');

function my_custom_menu() {
 add_menu_page('Custom Menu', 'Custom Menu', 'manage_options', 'my-top-level-handle', 'my_custom_menu_page', 'dashicons-admin-generic', 6);
 add_submenu_page('my-top-level-handle', 'Submenu Page', 'Submenu Page', 'manage_options', 'my-secondary-handle', 'my_secondary_menu_page');
}

function my_custom_menu_page() {
 // Content for the custom menu page
}

function my_secondary_menu_page() {
 // Content for the submenu page
}

This code is similar to the previous example, but it includes callback functions my_custom_menu_page and my_secondary_menu_page to display content for the custom menu page and the submenu page, respectively.

How to add a submenu page with custom capability in WordPress

Here’s an example of using the add_submenu_page function with a custom capability to add a submenu page in WordPress:

add_action('admin_menu', 'my_custom_menu');

function my_custom_menu() {
 add_menu_page('Custom Menu', 'Custom Menu', 'manage_options', 'my-top-level-handle', 'my_custom_menu_page', 'dashicons-admin-generic', 6);
 add_submenu_page('my-top-level-handle', 'Submenu Page', 'Submenu Page', 'edit_posts', 'my-secondary-handle', 'my_secondary_menu_page');
}

function my_custom_menu_page() {
 // Content for the custom menu page
}

function my_secondary_menu_page() {
 // Content for the submenu page
}

This code is similar to the previous examples, but it uses the edit_posts capability for the submenu page, allowing users with the “edit_posts” capability to access the submenu page.

Conclusion

In conclusion, the add_submenu_page function is an useful component for adding submenus to the WordPress admin dashboard. It allows developers to easily extend the functionality of their plugins or themes and provide users with a seamless experience. By utilizing this function, developers can create custom admin pages with ease, making it easier to manage and customize their WordPress sites. Overall, add_submenu_page is a valuable function for any WordPress developer looking to enhance their projects with custom admin pages.

Related WordPress Functions

in WordPress Functions