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.

Leave a Reply

Your email address will not be published. Required fields are marked *