WordPress Options Page Plugin Tutorial

I use option pages quite a bit when doing WordPress development. So much so that I created an open source WordPress plugin and would like to share it with you. You can download the source files or view the project on GitHub.

Note: this tutorial and plugin assumes that you are comfortable with the WordPress API and editing PHP files.

Downloading The Plugin

• After you download the zip file, go ahead and extract it.
• Rename the directory from “wordpress-options-plugin-master” to something more useful – like the name of your plugin. For this example, I will use “super-awesome-plugin.”
• Copy the plugin directory you just renamed to the wp_content/plugins directory of your WordPress installation.
• Open the plugin directory.

Getting Familiar With The Plugin Layout

There are 3 .php files in the plugin directory.

“my-plugin.php” is the main plugin file (which you will rename later) that defines the plugin name for WordPress, sets up some PHP definitions for use in the other files, and requires the other files.

The other PHP files have their code wrapped in a class. I did this mostly for namespacing. You will likely want to update the class names.

“admin-options.php” is the class that creates the options page for the WordPress dashboard.

“admin-input-fields.php” contains a class with methods to create input fields for use in “admin-options.php”.

Note: If you updated the class names, you will also need to update them in the require_once() functions to avoid errors. These can be found in “my-plugin.php” on lines 21 and 24 and in “admin-options.php” on line 3.

Some Configuration Required

Edit “my-plugin.php” and update the values for Plugin Name: , Author: , MY_PLUGIN_NAME, MY_PLUGIN_PREFIX, and MY_PLUGIN_OPTIONS to reflect your plugins name. Following along with my example of “Super Awesome Plugin” the updated code would look like this:

[code language=”php”]
/*
Plugin Name: Super Awesome Plugin
Author: Andrew Taylor
Version: 1.0
*/

/* DEFINE PLUGIN NAMESPACES */
//display name for end user
define(‘MY_PLUGIN_NAME’, ‘Super Awesome Plugin’);
//prefix for reuse
define(‘MY_PLUGIN_PREFIX’, ‘super_awesome_plugin_’);
//name of options stored in WordPress DB
define(‘MY_PLUGIN_OPTIONS’, ‘_super_awesome_plugin_options’);
[/code]

Rename “my-plugin.php” to also reflect your plugins name. For this example it would be “”super-aweome-plugin.php”

Setting Up Option Fields

Open up “admin-options.php” and look at line 66. Inside of <tbody></tbody> is where the inputs for the options page are defined.

The available input methods and examples are listed below. All of them require a string passed for $slug. The slug will be the key used for the input in the options array and should be a unique value. Try to make these lowercase and use underscores instead of spaces. For example 'first_name'$label is an optional string for the field label on the options page. If it is not set or passed as false, then the $slug will be used to generate the label. $description is an optional string that will be placed underneath the input to give the user some extra guidance. If omitted or passed as false, no description will be displayed. If an input methods accepts an argument of $options, it is required and should be an array of label/slug pairs. The label and slug can be the same or different.

Here are the examples from “admin-options.php”. You will need to replace these with your own set of options.

[code language=”php”]
//$admin_input_fields->text($slug=false, $label=false, $description=false);
$admin_input_fields->text(‘user_name’);
$admin_input_fields->text(‘phone_number’, false, ’10 Digit Phone Number in the format of 123-456-7890′);
$admin_input_fields->text(‘favorite_website’, ‘Favorite Website’, ‘Full URL – including http:// and www.’);

//$admin_input_fields->textarea($slug=false, $label=false, $description=false);
$admin_input_fields->textarea(‘user_profile’, false, ‘A little bit about you’);

//$admin_input_fields->checkbox($slug=false, $label=false, $description=false);
$admin_input_fields->checkbox(‘understands_binary’, ‘Do you understand binary?’, ‘There will be a test later!’);

//$admin_input_fields->page_select($slug=false, $label=false, $description=false);
$admin_input_fields->page_select(‘user_page’, ‘Your Page’);

//$admin_input_fields->select($slug=false, $options=false, $label=false, $description=false);
$admin_input_fields->select(‘like_sriracha’, array(‘No’ => ‘No’, ‘Yes’ => ‘Yes’, ‘I put Sriracha on everything!’ => ‘I put Sriracha on everything!’), ‘Do you like <a href=”http://www.huyfong.com/no_frames/sriracha.htm” target=”_blank”>Sriracha</a>?’);

//$admin_input_fields->radio($slug=false, $options=false, $label=false, $description=false)
$admin_input_fields->radio(‘pancakes_waffles’, array(‘Pancakes’ => ‘Pancakes’, ‘Waffles’ => ‘Waffles’, ‘Both’ => ‘Pancakes and Waffles’, ‘Neither’ => ‘Neither’), ‘Do you prefer pancakes or waffles?’, ‘Be honest…’);
[/code]

Testing

Go into the WordPress dashboard, activate your plugin, and head to the options page. Fill out some values and hit “Save Changes”.

Using Saved Options

The options are stored in a single array in the database. In order to use the options either in this plugin or a theme, you will need to get the array from the database using get_option(). It is also a good idea to check to make sure the value is set and not blank before displaying it. Here is an example of how you would retrieve and display “phone_number”

[code language=”php”]
<?php
//Get options from database
$my_plugin_options = get_option(MY_PLUGIN_OPTIONS);
//Display phone_number if it is set and is not empty
if( isset($my_plugin_options[‘phone_number’]) AND !empty($my_plugin_options[‘phone_number’]) ){
echo $my_plugin_options[‘phone_number’];
}?>
[/code]

The included file “shortcodes.php” has examples of retrieving the example options for use as WordPress shortcodes, but you certainly are not limited to shortcodes. I often use options to allow users to enter a phone number, social media urls, or other customizations.

Conclusion

This tutorial is pretty brief and assumes you know your way around WordPress. If you run into issues, use this on a project, or have general feedback, feel free to leave a comment.