add_menu_page() WordPress Function
The add_menu_page() function is used to add a top-level menu page to the WordPress admin panel. This function takes a number of arguments, including the menu page title, the capability required to view the page, the menu slug, the function to be called when the menu page is loaded, and the icon to be used for the menu page. The add_menu_page() function is a great way to add a custom page to the WordPress admin panel. This function allows you to specify the title, capability, slug, function, and icon for the page. By using this function, you can create a custom page that is tailored to your specific needs.
add_menu_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $callback = '', string $icon_url = '', int|float $position = null ) #
Adds a top-level menu page.
Contents
Description
This function takes a capability which will be used to determine whether or not a page is included in the menu.
The function which is hooked in to handle the output of the page must check that the user has the required capability as well.
Parameters
- $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 page and only include lowercase alphanumeric, dashes, and underscores characters to be compatible with sanitize_key().
- $callback
(callable)(Optional) The function to be called to output the content for this page.
Default value: ''
- $icon_url
(string)(Optional)The URL to the icon to be used for this menu.
- Pass a base64-encoded SVG using a data URI, which will be colored to match the color scheme. This should begin with 'data:image/svg+xml;base64,'.
- Pass the name of a Dashicons helper class to use a font icon, e.g. 'dashicons-chart-pie'.
- Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
Default value: ''
- $position
(int|float)(Optional) The position in the menu order this item should appear.
Default value: null
Return
(string) The resulting page's hook_suffix.
More Information
Notes
- Important Note: Since WordPress 4.4, you do not need to worry about making the position number unique to avoid conflicts. See trac ticket #23316 for more information.
- If you’re running into the “You do not have sufficient permissions to access this page” error, then you’ve hooked too early. The hook you should use is admin_menu.
- If you only want to move existing admin menu items to different positions, you can use the admin_menu hook to unset menu items from their current positions in the global $menu and $submenu variables (which are arrays), and reset them elsewhere in the array.
- This function takes a ‘capability’ (see Roles and Capabilities) which will be used to determine whether or not a page is included in the menu. The function which is hooked in to handle the output of the page must check that the user has the required ‘capability’ as well.
- If you are using the Settings API to save data, and need the user to be other than the administrator, will need to modify the permissions via the hook option_page_capability_{$option_group}, where $option_group is the same as option_group in register_setting() . Check out the Settings API.
Example allowing an editor to save data:
// Register settings using the Settings API
function wpdocs_register_my_setting() {
register_setting( 'my-options-group', 'my-option-name', 'intval' );
}
add_action( 'admin_init', 'wpdocs_register_my_setting' );
// Modify capability
function wpdocs_my_page_capability( $capability ) {
return 'edit_others_posts';
}
add_filter( 'option_page_capability_my-options-group', 'wpdocs_my_page_capability' );
Menu Structure
Default: bottom of menu structure
- 2 – Dashboard
- 4 – Separator
- 5 – Posts
- 10 – Media
- 15 – Links
- 20 – Pages
- 25 – Comments
- 59 – Separator
- 60 – Appearance
- 65 – Plugins
- 70 – Users
- 75 – Tools
- 80 – Settings
- 99 – Separator
For the Network Admin menu, the values are different:
- 2 – Dashboard
- 4 – Separator
- 5 – Sites
- 10 – Users
- 15 – Themes
- 20 – Plugins
- 25 – Settings
- 30 – Updates
- 99 – Separator
Source
File: wp-admin/includes/plugin.php
function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
$menu_slug = plugin_basename( $menu_slug );
$admin_page_hooks[ $menu_slug ] = sanitize_title( $menu_title );
$hookname = get_plugin_page_hookname( $menu_slug, '' );
if ( ! empty( $callback ) && ! empty( $hookname ) && current_user_can( $capability ) ) {
add_action( $hookname, $callback );
}
if ( empty( $icon_url ) ) {
$icon_url = 'dashicons-admin-generic';
$icon_class = 'menu-icon-generic ';
} else {
$icon_url = set_url_scheme( $icon_url );
$icon_class = '';
}
$new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url );
if ( null !== $position && ! is_numeric( $position ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: %s: add_menu_page() */
__( 'The seventh parameter passed to %s should be numeric representing menu position.' ),
'<code>add_menu_page()</code>'
),
'6.0.0'
);
$position = null;
}
if ( null === $position || ! is_numeric( $position ) ) {
$menu[] = $new_menu;
} elseif ( isset( $menu[ (string) $position ] ) ) {
$collision_avoider = base_convert( substr( md5( $menu_slug . $menu_title ), -4 ), 16, 10 ) * 0.00001;
$position = (string) ( $position + $collision_avoider );
$menu[ $position ] = $new_menu;
} else {
/*
* Cast menu position to a string.
*
* This allows for floats to be passed as the position. PHP will normally cast a float to an
* integer value, this ensures the float retains its mantissa (positive fractional part).
*
* A string containing an integer value, eg "10", is treated as a numeric index.
*/
$position = (string) $position;
$menu[ $position ] = $new_menu;
}
$_registered_pages[ $hookname ] = true;
// No parent as top level.
$_parent_pages[ $menu_slug ] = false;
return $hookname;
}
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
| Version | Description |
|---|---|
| 1.5.0 | Introduced. |