Tuesday , 16 July 2019
Home / Programming / WordPress / Plugins / WordPress Admin Menus – WordPress Plugin Tutorial
WordPress Admin Menus
WordPress Admin Menus

WordPress Admin Menus – WordPress Plugin Tutorial

This post is part of the WordPress Plugin tutorial series. To find a link to all tutorials in order, then please click here.

So far, our plugins have been very simple. To extend the functionality of our WordPress plugins, it’s best to have a set of options for a user to configure in their admin panel. Before we can get there, we first need to add a way to get there. We can easily do this by creating WordPress admin menus for our plugin.

There are 2 kinds of menus. Top-level menus and sub menus  We’ll be discussing how to create a top-level menus first and then learn how to add sub menus to it.

WordPress Admin Menus

Create a new plugin named wpmenuex and let’s set up our main plugin file.

As you can see, we’re hooking into a new action named admin_menu. We’ve also renamed the version check to avoid conflict with other plugins. The admin_menu action is a hook that is triggered when the admin visits the WordPress dashboard. If we didn’t do this and added the WordPress admin menus, then the plugin would throw an error. The menu can only be loaded in the WordPress dashboard. So, to capture the right moment to add the WordPress admin menus, we start adding menus when the action hook admin_menu is triggered.

We then call the function jk_add_admin_menu which will be defined in our menu.inc.php file. Let’s create that file right now and add the following code.

There are a couple of things to take in from here.  The admin_menu_page is a WordPress function that lets us create top-level menus. The admin_menu_page() function takes in 7 arguments.

  • Page Title – This refers to the title that you see at the top of your browser. For example, when you’re in the dashboard, you see Dashboard > Your Site Name — WordPress.
  • Menu Title – This refers to the title that you see on the menu. An example of this would be Dashboard, Posts, Media, Pages, etc that you already see in the default installation of WordPress.
  • Capabilities – WordPress has special user role system. There are 6 kinds of roles: Super Admin, Administrator, Editor, Author, Contributor and subscriber. Each of these roles are limited to certain permissions or capabilities. Capabilities are what a user can and can not do. There are a lot of capabilities. For our menu, we only want users who can manage options to be able to see the menu. So, we this to manage_options. For a list of all capabilities go here.
  • Menu Slug – This defines the URL to the page this menu will lead to if clicked. We want this URL to be unique. The best way to do this is by using the magic constant __FILE__. That way, this menu is always unique and you can avoid conflict with out menu items.

The first 4 parameters are required. The next 3 are optional, but are still good to define in your WordPress admin menus.

  • Function – It’s highly advised you define this function even if it optional. This function will define what’s displayed when the user visits the link from the WordPress admin menus. 
  • Icon Image – You can define your own menu icon image. It’s suggested you use the plugins_url to grab your icon image if you’re going to use one. We learned how to use it in a previous lesson. If you leave this blank, WordPress will use it’s default icon image.
  • Position – This defines the position in which your WordPress admin menus will appear. If set to none, then your menu will be placed at the bottom of the admin menu. If you want it to be placed at top, then set it to 1.

Before we activate our plugin, we must first define the function that our menu will use.  This will be put in a separate PHP file just to be organized and keep our code clean. Right BEFORE you include your menu file, include the file display-options.inc.php file first. Your code should look something like this.

Let’s create this file in our inc folder and add the following code.

We define the function jk_display_main_options() that we called for in our add_menu_page in our menus.inc.php file.

Save it and then activate your plugin. If you did everything right, you should be able to see the menu in your dashboard and be able to click it. When you click it you should be able to see all the settings you passed in the admin_menu_page() function. You should also see the message, “This is our options page”.

WordPress Admin Menus
WordPress Admin Menus

That’s all there is to it. In our next lesson, we’ll learn how to add a submenu which is fairly similar process to adding a top-level menu. Even though WordPress admin menus are recommended, you should limit on whether or not to create a top-level menu for all your plugins.

About Jasko Koyn

Check Also

WordPress Meta Boxes

WordPress Meta Boxes – WordPress Plugin Tutorial

WordPress meta boxes are used to display certain information or options in a page. It’s …

One comment

  1. thanks for the great tutorial series

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.