This is How to Add a Submenu Page to the WordPress Admin Menu
As a WordPress developer, you may need to add a custom submenu page to the WordPress admin menu for your plugin or theme. This is a common requirement, but it can sometimes be tricky to get right, especially if you encounter the common error of the submenu page not appearing in the admin menu.
In this article, we'll walk through the exact steps to add a submenu page to the WordPress admin menu, including how to fix any issues you may run into. By the end, you'll have a solid understanding of the WordPress admin menu functions and how to leverage them to create your own custom submenu pages.
Understanding the WordPress Admin Menu Structure
The WordPress admin menu is the main navigation menu that appears on the left side of the WordPress admin dashboard. This menu is made up of top-level menu items (like "Posts", "Media", "Pages", etc.) and submenu items that appear under each top-level menu.
To add a custom submenu page, you'll need to hook into the WordPress admin menu system using a few key functions:
add_menu_page()
: This function adds a top-level menu item to the WordPress admin menu.
add_submenu_page()
: This function adds a submenu item under an existing top-level menu.
add_action('admin_menu', 'my_plugin_menu')
: This hook allows you to run your custom menu-building function when WordPress loads the admin menu.
The key things to understand are:
- Submenus are always added under an existing top-level menu item
- You need to specify the slug of the parent menu item when adding a submenu
- There are various permissions and capability settings you can use to control who can access the submenu page
Step-by-Step: Adding a Submenu Page
Let's go through a step-by-step example of how to add a submenu page to the WordPress admin menu.
Imagine you have a WordPress plugin that needs to display a "Registrations" page under the "Theme Options" menu. Here's the code you would use:
function my_plugin_menu() {
add_submenu_page(
'theme-options', // Parent menu slug
'Registrations', // Page title
'Registrations', // Menu title
'manage_options', // Capability
'theme-options-registrations', // Menu slug
'wwpr_page_call' // Callback function
);
}
add_action('admin_menu', 'my_plugin_menu');
Let's break down what's happening here:
- The
add_submenu_page()
function is used to add the new submenu page.
- The
'theme-options'
parameter specifies the slug of the parent menu item under which the submenu will appear. In this case, it's the "Theme Options" menu.
- The
'Registrations'
parameters are the page title and menu title for the new submenu page.
- The
'manage_options'
capability determines who can access the submenu page. In this case, only users with the "manage_options" capability (typically administrators) can view it.
- The
'theme-options-registrations'
parameter is the unique slug for the submenu page.
- The
'wwpr_page_call'
parameter is the name of the callback function that will be executed when the submenu page is accessed. This is where you would add the content and functionality for the submenu page.
Finally, we hook this custom my_plugin_menu()
function into the 'admin_menu'
action, which tells WordPress to run it when the admin menu is being constructed.
Fixing the "Submenu Page Not Appearing" Issue
One common issue that can arise when adding a submenu page is that it simply doesn't appear in the admin menu. There are a few potential reasons for this:
-
Incorrect Parent Menu Slug: Double-check that the 'theme-options'
parent menu slug matches the actual slug of the top-level menu item you want to add the submenu under. This is a common source of errors.
-
Capability Mismatch: Ensure that the 'manage_options'
capability specified in the add_submenu_page()
function matches the capability required to access the parent menu item. If the user doesn't have the correct permissions, the submenu won't be visible.
-
Plugin/Theme Conflicts: It's possible that another plugin or your theme is interfering with the admin menu structure. Try disabling other plugins or switching to a default WordPress theme to isolate the issue.
-
Caching: WordPress and some hosting providers use caching mechanisms that could be hiding the new submenu page. Try clearing your browser cache and any WordPress caching plugins you have installed.
If you're still having trouble getting the submenu page to appear, the solution is often quite simple. Changing the 'edit.php?post_type=theme-options'
part of the code to the actual slug of the parent menu ('theme-options'
) should fix the issue.
function my_plugin_menu() {
add_submenu_page(
'theme-options',
'Registrations',
'Registrations',
'manage_options',
'theme-options-registrations',
'wwpr_page_call'
);
}
add_action('admin_menu', 'my_plugin_menu');
With this change, your submenu page should now appear correctly in the WordPress admin menu.
Adding Functionality to the Submenu Page
Now that you've successfully added the submenu page, it's time to add the actual content and functionality to the page. The 'wwpr_page_call'
callback function you specified earlier is where you'll do this.
Here's an example of what that function might look like:
function wwpr_page_call() {
?>
<div class="wrap">
<h1>Registrations</h1>
<p>This is where you can view and manage all registrations for your website.</p>
<?php
// Fetch and display registration data here
$registrations = get_registrations();
if ( $registrations ) {
echo '<table class="wp-list-table widefat fixed striped table-view-list">';
echo '<thead><tr><th>Name</th><th>Email</th><th>Date</th></tr></thead>';
echo '<tbody>';
foreach ( $registrations as $registration ) {
echo '<tr>';
echo '<td>' . $registration['name'] . '</td>';
echo '<td>' . $registration['email'] . '</td>';
echo '<td>' . $registration['date'] . '</td>';
echo '</tr>';
}
echo '</tbody>';
echo '</table>';
} else {
echo '<p>No registrations found.</p>';
}
?>
</div>
<?php
}
In this example, the wwpr_page_call()
function is responsible for rendering the content of the submenu page. It displays a heading, some introductory text, and then a table showing all the registration data fetched from a hypothetical get_registrations()
function.
You can customize this function to fit the specific needs of your plugin or theme, adding any necessary functionality, data displays, or form elements to the submenu page.
Conclusion
Adding a submenu page to the WordPress admin menu is a common task for plugin and theme developers. By understanding the WordPress admin menu structure and the key functions involved, you can create custom submenu pages that seamlessly integrate with the WordPress admin experience.
Remember, the key steps are:
- Use
add_submenu_page()
to define the submenu page
- Specify the correct parent menu slug and user capabilities
- Implement the callback function to add the page content
- Hook your menu-building function into the
'admin_menu'
action
And if you run into any issues with the submenu page not appearing, double-check the parent menu slug and user capabilities. With a bit of trial and error, you'll have your custom submenu page up and running in no time.
If you're looking for a tool that can help you identify and fix technical issues on your WordPress website to improve conversion rates, be sure to check out Flowpoint.ai. Flowpoint uses AI to automatically detect and recommend solutions for a wide range of technical problems that may be impacting your website's performance
Get a Free AI Website Audit
Automatically identify UX and content issues affecting your conversion rates with Flowpoint's comprehensive AI-driven website audit.