WordPress Plugin Development – Part 2 Admin Menu

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!

Prerequisites

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:

Crash Course on WordPress Plugin Development

Other requirements are the same for the entire series of WordPress plugin tutorials and include:

  • Knowledge of PHP
  • Experience in HTML and HTML5
  • Knowledge of JavaScript
  • 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:

<?php
/**
 * 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_action(‘admin_menu’,’add_notes_menu’);

function add_notes_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.

function create_notes_pg(){
include “../wp-content/plugins/jafty-plugin/inc/admin_notes.php”;
}//end create_notes_pg function
?>

Admin Page PHP File

Next we need to create the admin page. To accomplish this I like to create a new folder inside my plugin folder named “inc”. Then create a file appropriately named after the admin page in question such as admin_notes.php. For demonstration purposes, the below HTML will be the temporary contents of your inc/admin_notes.php file. You can add your own PHP, CSS and/or JavaScript code as needed.

<h1>Add/Edit/Delete Admin Notes</h1>

You can put whatever HTML, CSS, JavaScript and PHP code you desire here by editing the jafty-plugni/inc/admin_notes.php file….

Code Explained

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:

  1. create a folder on your desktop named “Jafty_plugin_two”, the name of this plugin.
  2. 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.
  3. Create a folder named “inc” inside of the main plugin folder, Jafty_plugin_two.
  4. 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.
  5. 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.

Summary

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.

Adding Main Menu and Submenu Items to WordPress Admin

This tutorial expands on a previous tutorial I wrote about Adding a Custom WordPress Admin Page and Menu Item. In this tutorial however, I will show you how to add both a main manu item and a submenu item because there is a trick to it that is very difficult to figure out just from reading the WordPress codex. That’s why I figured I’d write this quick tutorial to help others.

Here’s an image of a client of mine’s WordPress admin where I added both a top level menu to the WordPress admin and a submenu item under it or beside it on hover:

menu example

The image above has the area we are working on with a red border added around it to make it easy to see for this tutorial.

Adding Your Action

First, you have to add an action to your functions.php file. I did this wrong the first time because I tried to add one action for the main menu item and another for the sub menu item. It turns out that is incorrect. You need to add both your main menu item and sub menu item in a single action. Your action and call back function should something look like:

add_action( ‘admin_menu’, ‘addAdminMenu’ );

function addAdminMenu(){
add_menu_page(‘GEE Admin Settings’, ‘GEE Admin’, ‘manage_options’, ‘gee_admin_settings_page’, ‘admin_pg_function’, ”, 3);
add_submenu_page(‘gee_admin_settings_page’,’User Role Editor’, ‘Edit User Roles’,’manage_options’, ‘user_role_editor_slug’, ‘edit_user_roles_function’);
}

addAdminMenu Function Explained

In the above function we call both the add_menu_page and add_submenu_page functions. First lets look at the seven parameters for the add_menu_page function:

  1. ‘Gee Admin Settings’ – This is what shows up in the page tab of the browser. It is the title attribute for the admin page you are creating.
  2. ‘GEE Admin’ – This is what shows up in the left nav of the wp-admin page as the main menu item’s text. You can see this in the image provided above outlined in red.
  3. ‘manage_options’ – This is the capability required for users to be able to access this menu item. Use manage_options here unless you know what you are doing and have reason to use another capability here. The manage_options capability is usually set aside for admin users so other roles will not have access to your admin menu items.
  4. ‘gee_admin_settings_page’ – This is your menu item’s slug used to identify the menu item and should be unique. You will need this later to use with your submenu item.
  5. ‘admin_pg_function’ – This is the call back function. The call back function is the function that creates your actual admin page linked to the main menu item. It’s the page that opens when you click on the main menu item.
  6. ” – You’ll notice I left the sixth parameter blank by simply using two single quotes. This is because I am using the default menu icon which is the image of a gear. To use a custom icon for your menu item, include the image path and name here. This parameter is optional, but I had to include the single quotes to mark it’s place due to the fact that I also included the optional seventh parameter.
  7. 3 – finally, the seventh parameter here is optional and determines the menu order. Using “3” here causes the menu item to appear directly under the “Dashboard” menu item. make the number higher to make it appear further down in the navigation bar.

Now let’s look at the add_submenu_page function’s parameters:

  1. ‘gee_admin_settings_page’ – this has to be the exact same as your main menu item’s menu slug so notice how the same text is used in the add_menu_page function above it inside the AddAdminMenu function above.
  2. ‘User Role Editor’ – This is what shows up in the browser tab when the submenu item page is open. It is the title element for the submenu item’s page.
  3. ‘Edit User Roles’ – This is the text for the submenu item that shows up in the left navigation bar directly under the main menu item’s text.
  4. ‘manage_options’  – Just like in the previous function, this is the capability the user role must have to access these menu items.
  5. ‘user_role_editor_slug’ – This is the menu slug for this sub menu item.
  6. ‘edit_user_roles_function’ – This is the call back function that creates the page linked to from the submenu item. We will discuss these functons and give examples next.

The call back functions

Now we will discuss the call back functions called within the AddAdminMenu function’s inner functions of add_menu_page and add_submenu_page. The functions in this case were named admin_pg_function and edit_user_roles_function, but could be named anything, just make sure they are unique function names and that they are called inside of the add_menu_page and add_submenu_page functions respectively. Here are both function for creating the admin menu pages for the AddAdminMenu function:

function admin_pg_function(){
if(!current_user_can(‘manage_options’)){
wp_die( __( ‘You do not have sufficient permissions to access this page.’ ) );
}
/*add any form processing code here in PHP:*/
?>
<div style=”width:750px;”>
<h1><span style=”position:relative;top:-7px”>GoldEagleXpress.com Custom Admin Settings</span></h1>

<?php
/*add the rest of your page content above here if it’s HTML and below here if it’s PHP!*/
}/*end admin_pg_function function.*/
/*end cody by Ian L. to add custom menu item to wp-admin…*/

function edit_user_roles_function(){
if(!current_user_can(‘manage_options’)){
wp_die( __( ‘You do not have sufficient permissions to access this page.’ ) );
}
/*add any form processing code here in PHP:*/
?>
<div style=”width:750px;”>
<h1><span style=”position:relative;top:-7px”>GoldEagleXpress.com Custom User Role Settings</span></h1>

<?php
/*add the rest of your page content above here if it’s HTML and below here if it’s PHP!*/
}//end edit_user_roles_function function.
//############### end add main menu item to wp-admin ############

Summary

You will see if you cut and paste the code above, that it will simply create two menu items added to your navigation bar in your WordPress admin and two basically blank pages that you can go to by clicking on the new menu items. You will of course need to add some content in the last two functions here to add content to your admin pages. Good luck and happy coding!