This post is a part 6 of Creating a WordPress Admin Theme post series.
In this post we will see how to create new admin pages and also how to attach the existing menus. WordPress Menus API provides a very simple way to do all these operations.
Understanding WordPress Admin Menu
WordPress admin menu is the sidebar in wordpress admin panel. This admin menu bar has menu menu items and each of these menu items has sub menu items. WordPress admin menu API allows us to create menu items and also sub menu items.
In the above image dashboard, posts, pages, comments etc are menu items. Each of these menu items have sub menu items. Dashboard has updates and akismet stats sub menu items.
Every menu item and sub menu item has a page associated with it.
Creating Menu Items
New menu items can be created using add_menu_page wordpress function.
<?php
function add_new_menu_items()
{
//add a new menu item. This is a top level menu item i.e., this menu item can have sub menus
add_menu_page(
"Theme Options", //Required. Text in browser title bar when the page associated with this menu item is displayed.
"Theme Options", //Required. Text to be displayed in the menu.
"manage_options", //Required. The required capability of users to access this menu item.
"theme-options", //Required. A unique identifier to identify this menu item.
"theme_options_page", //Optional. This callback outputs the content of the page associated with this menu item.
"", //Optional. The URL to the menu item icon.
100 //Optional. Position of the menu item in the menu.
);
}
//this action callback is triggered when wordpress is ready to add new items to menu.
add_action("admin_menu", "add_new_menu_items");
function theme_options_page(){}
?>
function add_new_menu_items()
{
//add a new menu item. This is a top level menu item i.e., this menu item can have sub menus
add_menu_page(
"Theme Options", //Required. Text in browser title bar when the page associated with this menu item is displayed.
"Theme Options", //Required. Text to be displayed in the menu.
"manage_options", //Required. The required capability of users to access this menu item.
"theme-options", //Required. A unique identifier to identify this menu item.
"theme_options_page", //Optional. This callback outputs the content of the page associated with this menu item.
"", //Optional. The URL to the menu item icon.
100 //Optional. Position of the menu item in the menu.
);
}
//this action callback is triggered when wordpress is ready to add new items to menu.
add_action("admin_menu", "add_new_menu_items");
function theme_options_page(){}
?>
You can find the position of WordPress default menu items on add_menu_page official docs so that you know where to place your menu item. Higher the value lower its positioned.
Populate the menu item page based on weather you need WordPress Settings API or just want to manually display and store data.
Creating Sub Menu Items
Sub-menu items are added to top-level menu items. In the above code we created our top level menu item. Sub-menu items are created using add_submenu_page wordpress function.
<?php
function add_new_menu_items()
{
//add a new menu item. This is a top level menu item i.e., this menu item can have sub menus
add_menu_page(
"Theme Options", //Required. Text in browser title bar when the page associated with this menu item is displayed.
"Theme Options", //Required. Text to be displayed in the menu.
"manage_options", //Required. The required capability of users to access this menu item.
"theme-options", //Required. A unique identifier to identify this menu item.
"theme_options_page", //Optional. This callback outputs the content of the page associated with this menu item.
"", //Optional. The URL to the menu item icon.
100 //Optional. Position of the menu item in the menu.
);
//add a submenu for the theme-options menu item
add_submenu_page(
"theme-options", //Required. Slug of top level menu item
"Header Options", //Required. Text to be displayed in title.
"Header Options", //Required. Text to be displayed in menu.
"manage_options", //Required. The required capability of users.
"header-options", //Required. A unique identifier to the sub menu item.
"header_options_page", //Optional. This callback outputs the content of the page associated with this menu item.
"" //Optional. The URL of the menu item icon
);
}
//this action callback is triggered when wordpress is ready to add new items to menu.
add_action("admin_menu", "add_new_menu_items");
function theme_options_page()
{
}
function header_options_page()
{
}
?>
function add_new_menu_items()
{
//add a new menu item. This is a top level menu item i.e., this menu item can have sub menus
add_menu_page(
"Theme Options", //Required. Text in browser title bar when the page associated with this menu item is displayed.
"Theme Options", //Required. Text to be displayed in the menu.
"manage_options", //Required. The required capability of users to access this menu item.
"theme-options", //Required. A unique identifier to identify this menu item.
"theme_options_page", //Optional. This callback outputs the content of the page associated with this menu item.
"", //Optional. The URL to the menu item icon.
100 //Optional. Position of the menu item in the menu.
);
//add a submenu for the theme-options menu item
add_submenu_page(
"theme-options", //Required. Slug of top level menu item
"Header Options", //Required. Text to be displayed in title.
"Header Options", //Required. Text to be displayed in menu.
"manage_options", //Required. The required capability of users.
"header-options", //Required. A unique identifier to the sub menu item.
"header_options_page", //Optional. This callback outputs the content of the page associated with this menu item.
"" //Optional. The URL of the menu item icon
);
}
//this action callback is triggered when wordpress is ready to add new items to menu.
add_action("admin_menu", "add_new_menu_items");
function theme_options_page()
{
}
function header_options_page()
{
}
?>
We defined only one sub menu item but two sub menu items will be displayed. The first one is same as the top-level menu item.
You can populate the callback page display functions with forms or any other data. For storing, retrieving and deleting data from these pages use update_option(), get_option() and delete_option respectively. But most developers use WordPress Settings API to populate the pages and build options for themes and plugins.
You can also add sub menu items to WordPress default parent menu items such as users, comments, settings etc. You can find their slug in add_submenu_page official docs.
Menu items can be removed using remove_menu_page function. This takes the menu slug as input. We can remove pre existing menu items and also manually created menu items using this function.
