dmin pages are the heart and soul of plugins.
It’s easy to assume they are complex form-filled monsters, the sole purpose of which is to gather data from the user. The truth is, admin pages provide a familiar place to welcome new users, provide information, and display details for support and documentation.
In this short tutorial we’ll take a look at the basics of how to add these pages to the backend of WordPress. You can then combine this knowledge with other tutorials to create tabbed pages, AJAX functionality, overlays and more.
The Components of an Admin Page
There are two or three components to an admin page, depending on the functionality you are building:
- A menu entry – top-level or sub-level
- The page content
- Processing logic for forms – if needed
For the purposes of this tutorial we will not be looking at forms and form processing, we’ll leave that for another day. Right now what we’ll be concerned with is how to put the pages themselves into place.
Top-Level and Sub-Level Menus
There are two types of menu entries: Top-level and sub-level. I recommend – as does the WordPress Codex – that you think about whether your plugin really needs a top-level menu entry. Too many plugins add top-level entries, which end up polluting the admin heavily.
One example is WordTwit, which tweets new content. It is a great plugin, but it adds a top-level entry unnecessarily.
This is completely unnecessary, an entry in the settings section would do just fine. Some plugins like WooCommerce, bbPress and others add top level items validly; it really depends on how users interact with your product.
A good rule of thumb is: If users need to interact with your plugin daily you can use a top-level entry. If your admin page is just for settings, a sub-level entry in the Settings top-level menu is more appropriate.
Creating a Top-Level Admin Page
The first step is to create a menu entry with the add_menu_page()function. Here’s a full example, explanation ensues:
The function takes seven arguments. The first one is the page title, which defines the title tag; it is shown in the tab title, not on screen.
The second argument is the title that shows up in the menu.
Argument three is the capability required to access the menu. This can be used to restrict it to only admins, editors or authors.
Argument four is the menu slug, which is essentially used as the URL of the page.
Argument five is the function, which will handle the content of the page.
The next argument is the icon url. This can accept a number of formats. If a URL to an image is given the image will be used. You can also use Dashicons, which are built into WordPress, or even SVG.
The last argument defines where the menu will be placed. Argument five indicated the posts so I’ve used six to put this menu entry just underneath. Take a look at the Codex to see exactly what number to use for your desired position.
The next step is to create some content. All you need to do is create the function defined in argument five and echo some content. Here’s a very simple example you can start with:
Creating a Sub-Level Admin Page
There are quite a few functions you can use to add sub-level pages. The general add_submenu_page() will let you put sub-level entries anywhere, but all built-in top level pages have their own functions:
- To add a menu item under posts use
add_posts_page - To add a menu item under pages use
add_pages_page - To add a menu item under media use
add_media_page - To add a menu item under links use
add_links_page - To add a menu item under comments use
add_comments_page - To add a menu item under appearance use
add_theme_page - To add a menu item under plugins use
add_plugin_page - To add a menu item under users use
add_users_page - To add a menu item under tools use
add_management_page - To add a menu item under settings use
add_options_page
Each of these functions follow the same format: add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function);. The arguments should be familiar from our top-level example above.
You may want to add a sub-level menu to your own top level, in which case these specific function won’t be of much use to you. You’ll need to use add_submenu_page(). Let’s use this function to add an entry under our top level one created above:
As you can see this function is almost identical to the specific functions above, except for the first argument which specifies the slug of the parent element. In our case, this is myplugin/myplugin-admin-page.php.
Conclusion
As you can see, adding menu entries and displaying content is quite easy. The difficulty starts once this has been done. What to put on the page, how to arrange it, using Javascript and CSS to make the presentation great, making sure forms are secure and validated etc. These are things we’ll be taking a look at in future tutorials.
The goal of this article is to give you an understanding of the basics of menu and admin page creation so you can refer back to it when needed. Hopefully you can now create pages for your products. We’ll be tackling specific use-cases in another article soon.
Are there any specific use-cases you would like us to put together? Let us know in the comments below.