How to add a plugin Settings Page to the admin menu in WordPress

This tutorial is part of a series that tells my journey toward creating a WordPress plugin.

In order to add an item to the admin menu, we need to use the add_action() function and reference the action to the ‘admin_menu’. This will hook into the do_action(‘admin_menu’), which fires just before the administration menu loads in the admin (https://developer.wordpress.org/reference/hooks/admin_menu/)

The add_action() function receives at least two parameters: the hook and the function we want to execute at that moment.

Directory structure for a freshly baked WordPress plugin using wppb.me

If you take a look at the structure of the plugin made by the WPPB, you will see in there that we have an ‘admin’ directory. So this is where we should work for everything that implies administrative actions.

If we open class-{yourpluginname}-admin.php, we will see that in there are styles and scripts loaded specifically for admin purposes, and that’s all.

Let’s start adding the menu item in our constructor method:

add_action('admin_menu', array($this, 'addAdminMenuItems'), 9);

As you can see, we’ve said that we want to add an action to the admin_menu hook, and we reference the action to the current class ($this), and the ‘addAdminMenuItems()’ method. Also, we’ve set a priority for this action we are adding (9).

Now we only need to create the method. So let’s go almost to the end of our class and create the method that will add the menu page (https://developer.wordpress.org/reference/functions/add_menu_page/):

public function addAdminMenuItems() {
  //add_menu_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', string $icon_url = '', int $position = null )
  add_menu_page(
    $this->plugin_name,
    'Your plugin name',
    'administrator',
    $this->plugin_name,
    array(
      $this,
      'displayAdminDashboard',
    ),
    'dashicons-email',
    20
  );
}

As you can see, we’ve respected the format of the add_menu_page() function by passing the page title, menu title, the capability the user needs in order to see it, the menu slug, the function (method) we want to use to display the page, the icon (you can choose a different icon from here: https://developer.wordpress.org/resource/dashicons) and the position we want the item to have in the admin menu.

Since we’ve passed the ‘displayAdminDashboard()’ method to the add_menu_page() function let’s also create the method in our class. As you can see from the directory structure of the plugin, there is also a ‘partials’ directory inside the ‘admin’ directory. So, let’s call the main file in that ‘partials’ directory in the method:

public function displayAdminDashboard() {
  require_once 'partials/' . $this->plugin_name . '-admin-display.php';
}

Now, if we take a look at our admin menu, we will see that the menu item we defined appeared.

For the moment we will keep the admin dashboard page only for data reports related to the plugin, and we will create a submenu item that will send the administrators to the settings page of our plugin.

So let’s add a submenu in the same method we’ve started: ‘addAdminMenuItems()’. To add a submenu, we would have to use the ‘add_submenu_page()’ function (https://developer.wordpress.org/reference/functions/add_submenu_page/) which, beside the classic parameters, also receives a parent slug, in order to identify the parent menu item.

public function addAdminMenuItems() {
 //add_menu_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', string $icon_url = '', int $position = null )
add_menu_page(
  $this->plugin_name,
  'Your plugin name',
  'administrator',
  $this->plugin_name,
  array(
   $this,
   'displayAdminDashboard',
  ),
  'dashicons-email',
  20
 );
//add_submenu_page( string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null )
add_submenu_page(
  $this->plugin_name,
  'Your plugin Settings',
  'Settings',
  'administrator',
  $this->plugin_name.'-settings',
  array(
   $this,
   'displayAdminSettings',
  )
 );
}

The same way we created the dashboard page method and template, we should create the settings page. So, let’s create the displayAdminSetrings() method and also create a partial named ‘{yourpluginname}-admin-settings-display.php’ (just make a copy of the previous partials and paste it with the same name).

public function displayAdminSettings() {
 require_once 'partials/' . $this->plugin_name . '-admin-settings-display.php';
}

OK. That’s it for the menu items. Next we will start creating the settings page.

Sources

https://blog.wplauncher.com/create-wordpress-plugin-settings-page/