Here we will cover how to add menu items and admin pages to the WordPress admin area or the wp-admin dashboard. This will be the first lesson in the crash course on WordPress development series where you will actually be creating a full working WordPress plugin!
I explain a plugin’s file structure and how to start your first plugin file in PHP in the primer for this series. Click the following link to read the primer for this tutorial:
Other requirements are the same for the entire series of WordPress plugin tutorials and include:
- Knowledge of PHP
- Experience in HTML and HTML5
- CSS experience
- WordPress experience
- Knowledge of MySQL database
Create a Plugin that adds an Admin Menu to the WordPress Dashboard
Starting with the PHP file template we made in our primer the plugin file that creates an admin menu and page for your WordPress dashboard will look like:
* Plugin Name: Jafty Part Two
* Plugin URI: http://jafty.com/blog/crash-course-on-wordpress-plugin-development/
* Description: A Plugin that adds a menu item and admin page to the wp-admin dashboard.
* Version: 1.0
* Author: Ian L. of Jafty.com
* Author URI: http://jafty.com
* License: GPL2
//part two, add admin menu:
add_menu_page(‘Admin Notes’, ‘Admin Notes’, ‘manage_options’, ‘admin_notes’, ‘create_notes_pg’,”,3);
//add_submenu_page(‘admin_notes’,’Credits’, ‘Credits’,’manage_options’, ‘manage_notes_slug’, ‘create_credits_pg’);
}//end add_notes_menu function.
}//end create_notes_pg function
Admin Page PHP File
<h1>Add/Edit/Delete Admin Notes</h1>
Okay, some of the above code(not the HTML we hope) is a little confusing if you are not familiar with the WordPress function used, especially the add_menu_page and add_submenu_page function. They do what they suggest. add_menu_page adds an admin page and a top level menu item to the admin dashboard’s main left navigation menu. The add_submenu_page function, that we currently have commented out, would be used to add a submenu item to the admin navigation menu as well as another admin page. The submenu would appear under the main menu item set in the function’s parameters. I’ll go on to explain the add_menu_page function in detail below to help you better understand both.
WordPress add_menu_page Function
add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );
As demonstrated above, the add_menu_page function takes up to 7 parameters:
- page_title – this is what will show up inside the title HTML tag of the page and therefore shows up on the browser tab when the page is opened.
- menu_title – this is the menu text that shows up in the main admin dashboard’s navigation menu.
- capability – is the user capability a user must have in order to view the admin page you are adding.(no longer use user levels here as this has been depreciated)
- menu_slug – is the text that shows up in the URL when viewing your new admin page. (optionally you can use the PHP file name of the menu page here and not use the next function parameter to create the page. We do not use this method here though)
- function – is where you name the PHP function that creates the admin page.(technically this is optional, but this is a much needed option for the method we use for creating admin pages and menus. If you do not include this, you do not use a function to create the page, but include the file name of the menu page in the previous menu_slug parameter instead)
- icon_url – is an optional parameter that can be used to name an image file for the icon used in the navigation menu for this item. In our example above, we left this blank, but if you want to use the next parameter, as we have, you must put at least an empty quotation here to mark it’s place. When not used, the standard gear icon is used as the icon for the menu item.
- position – is an optional parameter used to define the position in the admin menu that you want your new menu item to appear. We used 3 here because that is the magic number that allows the menu item to appear directly after the “dashboard” menu item which is where I like to include more important menu items so they are easy to find. you can use a higher number here to make the menu item appear further down in the navigation menu.
Put it all together:
To put this all together into a working plugin, you could follow these simple steps:
- create a folder on your desktop named “Jafty_plugin_two”, the name of this plugin.
- name your main plugin PHP file(the first one we made above) “jafty-plugin-2.php” and place it insde of the Jafty_plugin_two folder.
- Create a folder named “inc” inside of the main plugin folder, Jafty_plugin_two.
- Name the last file we created, that has only the HTML for the new admin page, “admin_notes.php” and place it inside of the “inc” folder.
- Finally upload the Jafty_plugin_two folder to your plugins directory and go to your dashboard’s plugin tab and activate the “Jafty Part Two” plugin and you will see your admin menu item appear. Click on it and you should see something like the main image at the top of this article.
We demonstrated the code to create a functional plugin that adds a custom admin page and corresponding navigation menu item to the WordPress admin dashboard. Then we went on to explain the main function used to accomplish this. We also added the means in the plugin to expand it to include submenu items under the main menu item we added. We commented out this submenu code until it is needed. If you want to add a submenu item, simply remove the uncomment the line and make the first parameter the same as the fourth parameter in the corresponding add_menu_page function which is the menu slug parameter.