Professional WordPress Plugin Development. Brad Williams
plugin's settings page where users can configure your plugin options. WordPress features two methods for adding a plugin menu: a top‐level menu or a submenu item.
Creating a Top‐Level Menu
The first menu method for your plugin to explore in WordPress is a new top‐level menu, which is added to the Dashboard menu list. For example, Settings is a top‐level menu. A top‐level menu is common practice for any plugin that needs multiple option pages. To register a top‐level menu, you use the add_menu_page() function.
<?php add_menu_page( page_title, menu_title, capability, menu_slug, function, icon_url, position ); ?>
The add_menu_page() function accepts the following parameters:
page_title: Title of the page as shown in the <title> tags.
menu_title: Name of your menu displayed on the Dashboard.
capability: Minimum capability required to view the menu.
menu_slug: Slug name to refer to the menu; should be a unique name.
function: Function to be called to display the page content for the item.
icon_url: URL to a custom image to use as the menu icon. Also supports the dashicons helper class to use a font icon (e.g. dashicons‐chart‐pie).
position: Location in the menu order where it should appear.
Now create a new menu for your plugin to see the menu process in action. Use the admin_menu action hook to trigger your menu code. This is the appropriate hook to use whenever you create menus and submenus in your plugins.
<?php add_action( 'admin_menu', 'pdev_create_menu' ); function pdev_create_menu() { //create custom top-level menu add_menu_page( 'PDEV Settings Page', 'PDEV Settings', 'manage_options', 'pdev-options', 'pdev_settings_page', 'dashicons-smiley', 99 ); } ?>
As you can see, the admin_menu action hook calls your custom pdev_create_menu() function. Next you need to call the add_menu_page() function to register the custom menu in WordPress. Set the name of your menu to PDEV Settings, require that the user has manage_options capabilities (that is, is an administrator), and set the callback function to pdev_settings_page(). You also set the menu icon to use the built‐in smiley dashicon (covered in detail later in this chapter). The final parameter is the menu position, which defines where the menu will appear within the WordPress Dashboard's left menu.
The result is a custom registered menu as shown in Figure 3‐1.
FIGURE 3‐1: Custom registered menu
NOTE Menus are a common feature in WordPress plugins and are generally expected by users. It's a good idea to mention where your plugin settings can be found in the plugin description and documentation.
Adding a Submenu
Now that you have a new top‐level menu created, create some submenus for it, which are menu items listed below your top‐level menu. For example, Settings is a top‐level menu, whereas General, listed below Settings, is a submenu of the Settings menu. To register a submenu, use the add_submenu_page() function.
<?php add_submenu_page( parent_slug, page_title, menu_title, capability, menu_slug, function ); ?>
The add_submenu_page() function accepts the following parameters:
parent_slug: Slug name for the parent menu ( menu_slug previously defined)
page_title: Title of the page as shown in the <title> tags
menu_title: Name of your submenu displayed on the Dashboard
capability: Minimum capability required to view the submenu
menu_slug: Slug name to refer to the submenu; should be a unique name
function: Function to be called to display the page content for the item
Now that you know how submenus are defined, you can add one to your custom top‐level menu.
<?php add_action( 'admin_menu', 'pdev_create_menu' ); function pdev_create_menu() { //create custom top-level menu add_menu_page( 'PDEV Settings Page', 'PDEV Settings', 'manage_options', 'pdev-options', 'pdev_settings_page', 'dashicons-smiley', 99 ); //create submenu items add_submenu_page( 'pdev-options', 'About The PDEV Plugin', 'About', 'manage_options', 'pdev-about', 'pdev_about_page' ); add_submenu_page( 'pdev-options', 'Help With The PDEV Plugin', 'Help', 'manage_options', 'pdev-help', 'pdev_help_page' ); add_submenu_page( 'pdev-options', 'Uninstall The PDEV Plugin', 'Uninstall', 'manage_options', 'pdev-uninstall', 'pdev_uninstall_page' ); } ?>
The preceding code creates three submenus for your custom top‐level menu: About, Help, and Uninstall, as shown in Figure 3‐2. Each of these submenu items links to a different custom function that can contain any code you want to use for that submenu page.
FIGURE 3‐2: Submenus
NOTE Not all plugins will need submenus. For example, a plugin with a single settings page has no need for additional submenus. When creating your new plugin, it's important to determine if submenus will be needed for a good user experience.
Adding a Menu Item to an Existing Menu
If your plugin requires only a single options page, you may not need to create a custom top‐level menu. Instead, you can simply add a submenu to an existing menu, such as the Settings menu.
WordPress features many different functions to add submenus to the existing default menus in WordPress. One of these functions is the add_options_page() function. Now explore how the add_options_page() function works to add a submenu item to the Settings menu.
<?php add_options_page( page_title, menu_title, capability, menu_slug, function); ?>
The add_options_page() function accepts the following parameters:
page_title: Title of the page as shown in the <title> tags
menu_title: Name of your submenu displayed on the Dashboard
capability: Minimum capability required to view the submenu
menu_slug: Slug name to refer to the submenu; should be a unique name
function: Function to be called to display the page content for the item
Now add a submenu item to the Settings menu.
<?php add_action( 'admin_menu', 'pdev_create_submenu' ); function pdev_create_submenu() { //create a submenu under Settings add_options_page( 'PDEV Plugin Settings', 'PDEV Settings', 'manage_options', 'pdev_plugin', 'pdev_plugin_option_page'