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

[php]
class DevloungePluginSeries {
var $adminOptionsName = “DevloungePluginSeriesAdminOptions”;
function DevloungePluginSeries() { //constructor

}
[/php]

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:

[php]
//Returns an array of admin options
function getAdminOptions() {
$devloungeAdminOptions = array(‘show_header’ => ‘true’,
‘add_content’ => ‘true’,
‘comment_author’ => ‘true’,
‘content’ => ”);
$devOptions = get_option($this->adminOptionsName);
if (!empty($devOptions)) {
foreach ($devOptions as $key => $option)
$devloungeAdminOptions[$key] = $option;
}
update_option($this->adminOptionsName, $devloungeAdminOptions);
return $devloungeAdminOptions;
}
[/php]

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:

[php]
function init() {
$this->getAdminOptions();
}
[/php]

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

[php]
add_action(‘activate_devlounge-plugin-series/devlounge-plugin-series.php’, array(&$dl_pluginSeries, ‘init’));
[/php]

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.

[php]
//Prints out the admin page
function printAdminPage() {
$devOptions = $this->getAdminOptions();

if (isset($_POST[‘update_devloungePluginSeriesSettings’])) {
if (isset($_POST[‘devloungeHeader’])) {
$devOptions[‘show_header’] = $_POST[‘devloungeHeader’];
}
if (isset($_POST[‘devloungeAddContent’])) {
$devOptions[‘add_content’] = $_POST[‘devloungeAddContent’];
}
if (isset($_POST[‘devloungeAuthor’])) {
$devOptions[‘comment_author’] = $_POST[‘devloungeAuthor’];
}
if (isset($_POST[‘devloungeContent’])) {
$devOptions[‘content’] = apply_filters(‘content_save_pre’, $_POST[‘devloungeContent’]);
}
update_option($this->adminOptionsName, $devOptions);

?>

[/php]

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.

[php]