140 WordPress Administration Menus/Panels/Pages (Video)

Part of the “How to Write a WordPress Plugin” series

This Lesson – Overview

In previous lessons we introduced plugins, built a basic working plugin template file structure, created a simple plugin class for our plugin and produced the demonstration plugin, Text to Hyperlink.

In this series of lessons we’ll cover the writing of WordPress Administration Menus/Panels and Pages. These lessons will also expand upon the, Text to Hyperlink, lesson we covered earlier by providing an simple admin page and the ability to save data to the WordPress database.

Plugin & Theme Authors

As a plugin or theme author you will usually need to provide a method for your users to modify the plugin or theme settings (options). Asking your users, whose experience of PHP and CSS might be nil, to modify the PHP or CSS code, should not even be considered.

Even as a programmer, having to delve into source code every time parameters have to be changed is not a good idea. If your users need to interact with your plugin an administration menu an option page needs to be provided. It’s much more user friendly and complements your plugin or theme. The best way to present options to your users is through the use of an administration menu and options page.

Contents

Database and Variable Storage

One of the first requirements when constructing your administration page is where to store the data. There would be little point having an admin page if the data could not be stored and retrieved but needed re-entering upon every visit.

Luckily the developers of WordPress have an easy solution to this problem with “options”. For the moment just accept the fact that the method we will be using works, I will explain options and database storage in more details in a later lesson of this series. For now, all you have to do is follow the steps necessary to store your own admin variables in the WordPress database.

Administration Menu/Page Requirements

To add an administration menu to your plugin, you must do three things:

1. Create a function that contains the menu-building code.
2. Register the above function using the “admin_menu” action hook.
3. Create the HTML code for the page to be displayed when the menu item is clicked.

The first two steps are exactly the same as any other plugin. The third step, creating the HTML output, is usually the step I find the hardest. Simplicity and usability can take a lot of effort.

Administration Menu/Page Construction

When constructing the admin page you also need to follow three simple steps:

1. Retrieve submitted data (if any) from the database.
2. Check to see if any form data has been submitted.
3. Display the updated admin page options.

One thing to bear in mind at this stage, we will not be including localization in our examples to keep things simple. In reality I would advise including localization in order to let WordPress translate your plugin. Remember WordPress is international and including localization could significantly improve the uptake of your plugin or theme.

• We’ll cover localization in another lesson.

Determining the Location for Your Menu

When creating a new menu you must first decide at what layer level your menu should reside in the WordPress Dashboard menu structure. You have two choices:

• Top-level menu item.Displays as a new section in the Dashboard administration menu.Contains sub-level menu items.
• Sub-level menu item.These menu items are members of an existing menu, i.e. a top-level menu such as Posts, Pages, Plugins, Tools, Settings, User Defined, etc.

Only use a top-level menu if your requirement does not fit neatly into one of the standard WordPress categories or your new feature is unique and requires many screens to accomplish its task, i.e. a membership site, an accounting application, conference management, etc.

In general you’ll just need to decide in which WordPress top-level menu to place your sub-level menu item, i.e. a backup plugin would probably be added as a sub-menu item to the Tools top-level menu.

Menu Location Guide

WordPress suggests the following guide for determining the correct location for your menu item:

Dashboard

• The Only Top-Level Menus Which Should be Placed On the Dashboard are Those Central to The Operation of Your Site, an Application for Example. The Menu Structure Should Contain Everything Which Relates To The Application, Including Update Options.

Posts

• The Posts menu should contain tools for writing posts which are time sensitive.

Media

• The Media menu should contain tools for uploading and managing your pictures, videos, and audio.

Links

• The Links menu should contain tools for managing references to other blogs and sites of interest.

Pages

• The Pages menu should contain tools for writing your static content pages.

Comments

• The Comments menu should contain tools for the control and regulation of readers and responses to posts.

Appearance

• The Appearance menu should contain tools for the manipulation of themes, style files such as CSS, sidebars, etc.

Plugins

• The Plugins menu should contain controls dealing with plugin management. It should not contain configuration options for the plugin itself.

Users

• The Users menu should contain controls for user management.

Tools

• The Tools menu should manage the export, import, and backup of blog data. In other words, the maintenance of your blog.

Settings

• The Settings menu should contain tools for displaying options that only administrators should view or modify.

Ok, with the previous information in mind, lets see how we tell WordPress about our menus and options pages.

Top-Level Menu Items

To create a top-level menu you will use the add_menu_page() function.

This function creates a new top level menu section in the Dashboard admin menu sidebar and registers a hook to callback your function for outputting the page content when the linked menu page is requested.

The parameter values for the add_menu_page() function are as follows:

Usage

 
<?PHP
add_menu_page( $page_title, // Text displayed in the title tag of the menu page
               $menu_title, // Screen name of the menu item
               $capability, // User authentication access control
               $menu_slug, // Unique name to refer to this menu item
               $function, // Displays page content for menu page
               $icon_url, // URL to the icon for this menu
               $position ); // Placement in the menu order (default bottom)
?>

Parameter Values:

• $page_title(string) (required)Text displayed in the title tags of the menu page.
• $menu_title(string) (required)Screen name of the menu item.
• $capability(string) (required)The capability is the user authentication access control requirement for this menu item. There are about thirty capabilities in WordPress. The best place to find out more about this requirement is the WordPress codex. You should generally use the ‘manage_options’ capability here as the user won’t be able to save options without it.
• $menu_slug(string) (required)The unique slug name to refer to this menu item.
• $function(string / array) (optional) (recommended)The function string or array if your using a plugin class like us, is the name of the function which will display the option page content for the menu item.Its important to note that the function which is hooked in to handle the output of the page must check that the user has the required capability, that is, they have the required access level.
• $icon_url(string) (optional)The url to the icon to be used for this menu.
• $position(integer) (optional)The position in the menu order this menu should appear. The default is at the bottom of the menu structure.WARNING: if 2 menu items use the same position attribute, one of the items may be overwritten so that only one item displays!

Example Top-Level Menu

In this example the add_action() function is using the admin_menu hook to register_my_custom_menu() function.

This function uses the add_menu_page() function to create a top-level menu which calls the function my_custom_menu_page() to open the associated page.

Take note of how the my_custom_page() function immediately checks user permissions before doing anything else. This check should be done on every menu page you create.

 
<?PHP
add_action('admin_menu', 'register_my_custom_menu');
function register_my_custom_menu() {
   add_menu_page( 'My Custom Menu Page Title', // $page_title
                  'My Custom Menu Title', // $menu_title
                  'manage_options', // $capability
                  'my-custom-menu-page-slug', // $menu_slug
                  'my_custom_menu_page', // $function
                  'http://mywebsite/myicon.ico', // $icon_url
                  3 ); // $position
}
function my_custom_menu_page() {
   // Does the user have the right permissions?
   if (!current_user_can(’manage_options’)) {
      wp_die( ’Sorry, you do not have permission to access this page.’);
   }
   echo '<h3>My Custom Menu Page</h3>';
}
?>

Sub-Level Menus Items

With your top-level menu chosen, you are ready to define sub-level menu item(s) using the add_submenu_page() function.

• Add the sub-level menu item(s) in the order you want them displayed.

The parameter values for the add_submenu_page() function are as follows:

Usage

 
<?PHP
add_submenu_page( $parent_slug, // slug name of the parent menu
                                // or the file name of a standard WordPress admin page
                  $page_title,  // Text displayed in the title tag of the menu page
                  $menu_title,  // Screen name of the menu item
                  $capability,  // User authentication access control
                  $menu_slug,   // Unique name to refer to this menu item
                  $function);   // Displays page content for menu page
?>

Parameter Values:

$parent_slug (string) (required)

The slug name for the parent menu or the file name of a standard WordPress admin page.

Example: Calls using a standard WordPress admin page:
Dashboard:  add_submenu_page( 'index.PHP', ... );
Posts:      add_submenu_page( 'edit.PHP', ... );
Media:      add_submenu_page( 'upload.PHP', ... );
Links:      add_submenu_page( 'link-manager.PHP', ... );
Pages:      add_submenu_page( 'edit.PHP?post_type=page', ... );
Comments:   add_submenu_page( 'edit-comments.PHP', ... );
Appearance: add_submenu_page( 'themes.PHP', ... );
Plugins:    add_submenu_page( 'plugins.PHP', ... );
Users:      add_submenu_page( 'users.PHP', ... );
Tools:      add_submenu_page( 'tools.PHP', ... );
Settings:   add_submenu_page( 'options-general.PHP', ... );

The remainder of the parameters are exactly the same as those of the top-level menu parameters.

Example Sub-level Menu

In this sub-level menu example the add_action() function is using the admin_menu hook to register_my_custom_submenu_page() function.

This function uses the add_submenu_page() function to create a sub-level menu in the top-level Tools menu. This calls the my_custom_submenu_page() function to open the associated page.

Once again, take note of how the my_custom_submenu_page() function immediately checks user permissions before doing anything else. This check should be done on every menu page you create.

 
<?PHP
add_action('admin_menu', 'register_my_custom_submenu_page');

function register_my_custom_submenu_page() {

   // Add submenu to Tools top-level menu
   add_submenu_page( 'tools.PHP', // $parent_slug
                     'My Custom Submenu Page Title', // $page_title
                     'My Custom Submenu Title', // $menu_title
                     'manage_options', // $capability
                     'my-custom-submenu-page-slug', // $menu_slug
                     'my_custom_submenu_page' ); // $function
}

function my_custom_submenu_page() {

   // Does the user have the right permissions?
   if (!current_user_can(’manage_options’)) {
      wp_die( ’Sorry, you do not have permission to access this page.’);
   }
   echo '<h3>My Custom Submenu Page</h3>';
}
?>

Using Wrapper Functions

To make life a little easier and since most sub-level menus belong under the Settings, Tools, or Appearance menus, WordPress supplies wrapper functions that make adding sub-level menu items to those top-level menus less complicated.

Note: Some of the functions names don’t match the admin UI as they have changed over time.

General Syntax

 
function_name ( $page_title, // Text displayed in the title tag of the menu page
                $menu_title, // Screen name of the menu item
                $capability, // User authentication access control
                $menu_slug,  // Unique name to refer to this menu item
                $function ); // Displays page content for menu page

Menu Function Name
Dashboard   add_dashboard_page ( ... );
Posts       add_posts_page ( ... );
Media       add_media_page ( ... );
Links       add_links_page ( ... );
Pages       add_pages_page ( ... );
Comments    add_comments_page ( ... );
Appearance  add_theme_page ( ... );
Plugins     add_plugins_page ( ... );
Users       add_users_page ( ... );
Tools       add_management_page ( ... );
Settings    add_options_page ( ... );

Conclusion – Summary

Well, that’s all for this tutorial introducing top-level and sub-level admin menus, see you in the next lessons where we will write some code using our plugin class to demonstrate what we have covered here.

Links Used in This Article