This post was written as part of the How to Write a WordPress Plugin series.

Any plugin that needs user input, such as changing a variable, should have some kind of administration panel. Building a administration panel isn't all that difficult, so it annoys me when plugin authors decide not to build one and want plugin users to modify PHP code. Asking users -- whose experience with PHP might be nil -- to modify code is generally not a good idea. This post will go into what it takes to successfully create an admin panel for your plugin.

A Place to Store the Variables

One of the first problems you will likely encounter when constructing your own admin panel is where exactly to store the variables. Luckily WordPress makes it quite easy with options. I will explain options and database storage in a later post in this series. For now, all you have to do is nod your head and follow the steps to store your own admin variables in the WordPress database.

The first thing I usually do with regards to options is to assign a "unique" name for my admin options. I store this in the form of a member variable inside my class. In the case of the Devlounge Plugin Series plugin, I added this variable declaration to the DevloungePluginSeries class:

Name Your Admin Options

Line 2 shows where I added in my member variable. I named my variable adminOptionsName and gave it the long and unique value of DevloungePluginSeriesAdminOptions.

Set Your Admin Default Options

You're going to need a place to initialize your admin options, especially when a user first activates your plugin. However, you also need to make these options upgrade-proof just in case you decide to add more options in the future. My technique is to provide a dedicated function to call your admin options. Your plugin needs may be different, but most admin panels aren't incredibly complicated so one function for your admin options should be sufficient.

Here's the function I inserted in the DevloungePluginSeries class:

What this function does is:

• Assigns defaults for your admin options (lines 3 - 6).
• Attempts to find previous options that may have been stored in the database (line 7).
• If options have been previously stored, it overwrites the default values (lines 8 - 11).
• The options are stored in the WordPress database (line 12).
• The options are returned for your use (line 13).

Initialize the Admin Options

The getAdminOptions can be called at anytime to retrieve the admin options. However, what about when the plugin is first installed (er, activated)? There should be some kind of function that is called that also retrieves the admin options. I added the following function into the DevloungePluginSeries class:

Short, sweet, and simple. An action, however, is required to call this init function.

This action is a little complicated, but easy to figure out. Here's what the action does:

• You tell it to run when a plugin has been activated.
• You give it the path to the main plugin PHP file, which is devlounge-plugin-series/devlounge-plugin-series.php. This of course is assuming that your plugin is properly placed in the wp-content/plugins/ directory.
• You pass a reference to the instance variable dl_pluginSeries and call the init function.

So anytime the plugin is activated, the init function is called for the Devlounge Plugin Series plugin.

How the Admin Panel Works

Before I delve into the code of constructing the actual admin panel, it will be beneficial to describe the behavior of the admin panel. Here are the steps you'll want to take for setting up your admin panel:

• Check to see if any form data has been submitted.
• Output notifications if form data is present.
• Display the admin panel options.

One thing that may confuse you greatly in the admin panel is the use of the _e WordPress function. The _e function allows WordPress to search for a localized version of your text. This will help WordPress potentially translate your plugin in the future. The function works like a normal echo, but instead you pass it your text and an identifier variable (typically your plugin name). An example would be:

_e('Update Settings', 'DevloungePluginSeries')

This code would work the same way as: echo "Update Settings".

Set up the Admin Panel Function

The first thing we want to do is set up a function that will actually print out the admin panel. The function's name will be printAdminPage. This next bit of code will read in the options we specified earlier and check to see if any post options have been submitted. All the code in this section is assumed to be within the printAdminPage function.

All the above code does is load in the options and test to make sure each portion of the form is submitted. The if-statement overkill isn't necessary, but sometimes it is useful for debugging. The first form variable that is tested as being set is update_devloungePluginSeriesSettings. This variable is assigned to our "Submit" button. If that isn't set, it's assumed that a form hasn't been submitted.

As promised, in line 16, I use the apply_filters function to format the content for saving in the database.

The next bit of code will display the HTML form that is necessary for the admin panel. It's a little involved, so I'll summarize it here. All the code is doing is displaying the form elements and reading in options.

One observation to make in the above code is the reference to the options and how the HTML and PHP is integrated.

Set up the Admin Panel Action

Now the the printAdminPage function is added, we need to call it through an action. First a function must be set up right above the actions that it outside the scope of the class.

The above code does this:

• A function named DevloungePluginSeries_ap is created.
• Variable dl_pluginSeries is tested for existence (lines 4 - 7). This variable references our class.
• An admin page named "Devlounge Plugin Series" is initialized and our printAdminPage function is referenced (lines 8-10).

The add_options_page function format is described by WordPress as: add_options_page(page_title, menu_title, access_level/capability, file, [function]);

The access level (in this case a 9) is described in more detail at the Users Levels page in the WordPress codex.

An action must now be set up to call the DevloungePluginSeries_ap function:

Conclusion

We now have an admin menu that we can use to set our plugin's behavior. The code to influence the behavior of the plugin was added, but was not described here. You can download the current version of the Devlounge Plugin Series plugin regarding administrative panels.

If you were to test out the plugin code above, you would see an admin panel for the plugin and be able to manipulate its output.

Download the Code Used In This Post

For further reading, please check out these links:

• Adding Administration Menus
• WordPress User Levels