11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

Unlimited asset downloads!

From $16.50/m 

CODE > WORDPRESS PLUGINS

Creating Custom WordPress Administration

Pages, Part 1
by Tom McFarlin Sep 2, 2016
Read Time: 11 mins Languages: English

This post is part of a series called Creating Custom WordPress Administration Pages.

 Creating Custom WordPress Administration Pages, Part 2

In a previous series, I provided an in-depth guide to working with the WordPress

Settings API. For those who are new to WordPress or who have been using other
tools such as The Customizer to handle various options, it may be something that
you have not had to use in your theme or plugin development.

As stated in the Codex:

The Settings API, added in WordPress 2.7, allows admin

pages containing settings forms to be managed semi-
automatically. It lets you define settings pages, sections
within those pages and fields within the sections.

I don't think it's something that's required to learn, but it's something that you
should know exists and know how to work with it if you find yourself needing to
introduce option pages into the WordPress administration area.

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 1/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

It's a powerful, albeit somewhat complex, API that provides us with a lot of
functionality. Ultimately, it allows us to do a lot of work on the server side and
minimal work on the client side.

But what about the times when we're working with a custom solution for clients
and we need a little more flexibility than the Settings API provides? For example,
say we need to build a plugin that will have a settings page but needs a more
flexible set of options and tailored validation functionality?

In those cases, it's possible to write our own custom WordPress administration
pages. In this series, we're going to take a look at how to do exactly that.

Before We Start

As with most tutorials like this, it's important to make sure that you have
everything in place to follow along so that you can work with the source code
that we cover throughout the series.

For this tutorial, I'm assuming:

You have a local development environment setup relative to your operating

system.
You have a copy of WordPress installed and ready to be used for installing a
plugin.
You're familiar with WordPress plugin development practices.
You're comfortable working with PHP and HTML.

If you're not familiar with how to set up a local development environment that
includes WordPress, please see this series for how to do just that. 

And if you're relatively comfortable with PHP, even if it's just reading the
language, then I'll do the best I can to provide clear instructions and comments
for each bit of code that we share.

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 2/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

Once all of this is in place, we're ready to begin working on our plugin.

Custom WordPress Administration Settings

By the end of this series, we're going to have a plugin that meets the following
requirements:

Adds a new submenu item to the existing WordPress menu system.

Adds a new settings page that corresponds to the new submenu item.
Sanitizes and serializes options on the page.
Validates and returns the values that were saved and renders them
accordingly.

Furthermore, we'll make sure that we approach this in the most modular way
possible using the WordPress Coding Standards and similar practices to make
reading, writing, and maintaining our plugin as easy as possible.

Advertisement

1. The Plugin Bootstrap

The first thing that we need to do is to create the plugin bootstrap. This will
include creating a directory to house the plugin's files, a basic README, a copy of
https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 3/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

the license, a bootstrap file that will eventually be used to start the plugin, and a
directory that will be used to hold the classes related to the administrative
functionality.

The files are available for download as an attachment to this post but, in the
meantime, you can see what my directory looks like below:

Furthermore, the contents of the plugin bootstrap are simple. Review the
following code for the single PHP file custom-admin-settings.php , and then I'll discuss
it in more detail below the block.

01 <?php
02 /**
03  * The plugin bootstrap file
04  *
05  * This file is read by WordPress to generate the plugin information in the
06  * plugin admin area. This file also defines a function that starts the plugin.
07  *
08  * @link              https://code.tutsplus.com/tutorials/creating-custom-admin-pages-i
09  * @since             1.0.0
10  * @package           Custom_Admin_Settings
11  *
12  * @wordpress-plugin
13  * Plugin Name:       Custom Admin Settings
14  * Plugin URI:        http://code.tutsplus.com/tutorials/creating-custom-admin-pages-in
15  * Description:       Demonstrates how to write custom administration pages in WordPres
16  * Version:           1.0.0
17  * Author:            Tom McFarlin
18  * Author URI:        https://tommcfarlin.com
19  * License:           GPL-2.0+
20  * License URI:       http://www.gnu.org/licenses/gpl-2.0.txt
https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 4/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

21  */
22  
23 // If this file is called directly, abort.
24 if ( ! defined( 'WPINC' ) ) {
25      die;
26 }
27  
28 add_action( 'plugins_loaded', 'tutsplus_custom_admin_settings' );
29 /**
30  * Starts the plugin.
31  *
32  * @since 1.0.0
33  */
34 function tutsplus_custom_admin_settings() {
35  
36 }

Notice that in the code above, there's actual very little code. Instead, it's a lot of
comments. The main block of comments at the top of the file explains what the
file does.

The area below the @wordpress-plugin tag is what WordPress will read in order to
generate the plugin's title, description, and relative links in the plugin dashboard
of WordPress.

Next, we prevent anyone from accessing the file directly. And, finally, we create a
custom function to be fired with the plugins_loaded hook. This function is what will
be used to start the plugin.

At this point, you should be able to log in to WordPress, navigate to the Plugin's
Dashboard, and then see the plugin available to activate. Go ahead and
click Activate.

Nothing will happen yet, but we'll start adding functionality as we work
throughout this tutorial.

2. Creating the Submenu Item

In order to begin working on the plugin, let's first introduce a submenu item. To
do this, we'll need to take advantage of the WordPress API function
https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 5/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

add_options_page . This function will require five parameters:

1. the text to display as the title of the corresponding options page

2. the text to display as the submenu text for the menu item
3. the capabilities needed to access this menu item
4. the menu slug that's used to identify this submenu item
5. a callback to a function that's responsible for rendering the admin page

Note that we'll be using classes to organize our functionality, so much of what
we're doing is going to be object-oriented.

First, let's create a class in the admin directory called class-submenu.php . Since this
class is responsible for introducing a new submenu, we'll have it named
descriptively.

The contents of the class should look like this:

01 <?php
02 /**
03  * Creates the submenu item for the plugin.
04  *
05  * @package Custom_Admin_Settings
06  */
07  
08 /**
09  * Creates the submenu item for the plugin.
10  *
11  * Registers a new menu item under 'Tools' and uses the dependency passed into
12  * the constructor in order to display the page corresponding to this menu item.
13  *
14  * @package Custom_Admin_Settings
15  */
16 class Submenu {
17  
18         /**
19      * A reference the class responsible for rendering the submenu page.
20      *
21      * @var    Submenu_Page
22      * @access private
23      */
24     private $submenu_page;
25  
26     /**
27      * Initializes all of the partial classes.
28
https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 6/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

29      *
30      * @param Submenu_Page $submenu_page A reference to the class that renders the
31      *                                                                   page for the p
32      */
33     public function __construct( $submenu_page ) {
34         $this->submenu_page = $submenu_page;
35     }
36  
37     /**
38      * Adds a submenu for this plugin to the 'Tools' menu.
39      */
40     public function init() {
41          add_action( 'admin_menu', array( $this, 'add_options_page' ) );
42     }
43  
44     /**
45      * Creates the submenu item and calls on the Submenu Page object to render
46      * the actual contents of the page.
47      */
48     public function add_options_page() {
49  
50         add_options_page(
51             'Tuts+ Custom Administration Page',
52             'Custom Administration Page',
53             'manage_options',
54             'custom-admin-page',
55             array( $this->submenu_page, 'render' )
56         );
57     }
}

At this point, the plugin will still not do anything. We still need to create the
actual Submenu_Page class, and then we need to wire the classes up to the bootstrap
file.

3. Creating the Submenu Page

Let's start with the Submenu_Page class first. Create another file in the admin

directory and call it class-submenu-page.php . Then, in the file, add the following code.

01 <?php
02 /**
03  * Creates the submenu page for the plugin.
04  *
05  * @package Custom_Admin_Settings
06  */
07  
08 /**
09  * Creates the submenu page for the plugin.
https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 7/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

10  *
11  * Provides the functionality necessary for rendering the page corresponding
12  * to the submenu with which this page is associated.
13  *
14  * @package Custom_Admin_Settings
15  */
16 class Submenu_Page {
17  
18         /**
19      * This function renders the contents of the page associated with the Submenu
20      * that invokes the render method. In the context of this plugin, this is the
21      * Submenu class.
22      */
23     public function render() {
24         echo 'This is the basic submenu page.';
25     }
26 }

When this page renders, it will simply display the text: "This is the basic submenu
page." We'll eventually get into adding new options. But first, let's bring this
plugin to life by instantiating it within our bootstrap file.

4. Rendering the Menu and the Page

Next, open the custom-admin-settings.php file that we created earlier in this
tutorial. Let's go ahead and write the code necessary to introduce the new
submenu item and its associated page.

Remember, the Submenu class requires that an instance of the Submenu_Page class
be passed into its constructor, and then we need to call the init method on the
Submenu class to set the whole thing into motion.

In code, this looks like the following:

01 <?php
02  
03 // If this file is called directly, abort.
04 if ( ! defined( 'WPINC' ) ) {
05      die;
06 }
07  
08 // Include the dependencies needed to instantiate the plugin.
09 foreach ( glob( plugin_dir_path( __FILE__ ) . 'admin/*.php' ) as $file ) {
10     include_once $file;
11 }

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 8/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

12  
13 add_action( 'plugins_loaded', 'tutsplus_custom_admin_settings' );
14 /**
15  * Starts the plugin.
16  *
17  * @since 1.0.0
18  */
19 function tutsplus_custom_admin_settings() {
20  
21     $plugin = new Submenu( new Submenu_Page() );
22     $plugin->init();
23  
24 }

At this point, you should be able to refresh your installation of WordPress,

activate the plugin (if it's not already activated), and then see your new page
rendered within the administration area.

In the next article, we'll look at how we can begin introducing actual settings into
the screen. Additionally, we'll look at some best practices in terms of working
with our template and our template partials, and then we'll see how they will be
wired up to the APIs responsible for not only saving them but how we will
sanitize and validate them.

But before we go that far, I want to talk a little bit about the class design that
we've seen in this tutorial. Generally speaking, I want to talk about why we have a
https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 9/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

class for the Submenu and the Submenu_Page and how it relates to the bootstrap file.

A Word on Class Responsibility

For those of you who are familiar with the Single Responsibility Principle, this
section may not be of any interest to you. But if who need a refresher or want to
hear more, then read on.

Gather together the things that change for the same

reasons. Separate those things that change for different
reasons.

There's more much to this, but if you were to look at each of our classes (at least
the two we have thus far), then it's clear that the reasons our classes may change
are as follows:

The contents of the submenu may change. Anything from the page title to
the menu slug and everything in between.
The way the page renders its contents may (and will change). Specifically,
right now it does nothing but echo a string. Soon, it will include a particular
file. After that, it may need to include multiple files.

The above two reasons are two very different reasons that classes may change, so
keeping them together in the same class would violate the above principle.

Ultimately, I bring this up not only to help shed light on greater software
engineering principles that can be applied in WordPress, but also to help prepare
you for some of the reasons we're going to be breaking apart certain things that
are usually large files within the context of plugins.

The nice thing about learning principles is that they can be applied in multiple
projects and not just in single projects. You learn them, you practice using them,

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 10/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

and you get better at architecting solutions for other people. 

The learning curve may be steep, but once you begin that uphill climb, it gets
easier and easier to incorporate the principles into your day-to-day work. Then,
the work you're providing for others becomes much easier to maintain over time.

Advertisement

Conclusion

Don't forget that you can download the plugin in its current state from this post.
As we progress through the series, I'll make the latest version available on each
post so you will be able to follow along with the code covered in each tutorial,
tinker with it, and prepare questions that you may want to ask in the comments.

As a side note, if you're looking for other utilities to help you build out your
growing set of tools for WordPress or for code to study and become more well-
versed in WordPress, don't forget to see what we have available in Envato Market.

Remember, you can catch all of my courses and tutorials on my profile page, and
you can follow me on my blog and/or Twitter at @tommcfarlin where I talk about

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 11/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

various software development practices and how we can employ them in

WordPress.

Finally, don't hesitate to leave any questions or comments in the feed below. I do
my best to participate and answer every question or critique you offer as it relates
to this project.

Resources

The Complete Guide to the WordPress Settings API

The Settings API
plugins_loaded
add_options_page
Single Responsibility Principle

Advertisement

WordPress Plugins WordPress CMS Web Development

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 12/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

Tom McFarlin
Tuts+ Editor, Owner and Lead Developer at Pressware

Tom is a self-employed developer who loves writing, building, and sharing

WordPress-based projects. He runs Pressware where he provides WordPress goods
and services. You can follow him on Twitter.

tommcfarlin

 FEED  LIKE  FOLLOW

Weekly email summary

Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on
learning about the next big thing.

Update me weekly

Download Attachment

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 13/14
11/11/21, 4:05 AM Creating Custom WordPress Administration Pages, Part 1

Advertisement

QUICK LINKS - Explore popular categories

ENVATO TUTS+ 

JOIN OUR COMMUNITY 

HELP 

30,299 1,316 49,803

Tutorials Courses Translations

Envato Envato Elements Envato Market Placeit by Envato Milkshake All products Careers Sitemap

© 2021 Envato Pty Ltd. Trademarks and brands are the property of their respective owners.

https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1--cms-26829 14/14