Codeable info

Creating a Simple Options Page

Posted on by in WordPress Tutorials

An options page is essential to any plugin or theme that requires the end user to enter or modify custom information. Even if you just want to display some instructions, an options page is still a good idea to incorporate into your software. Luckily, the process is not difficult for beginner developers with prior experience in HTML and PHP. All you need to do is register the settings and page, then create the page itself. For clarity in your code, it might be convenient to place all of the following code into a separate file, possibly called options.php or admin.php, and use the

include()

function in your main functions file to run the code for the options page when needed.

Registering the Settings and Page

As with most development for WordPress, you have to tell WordPress what you are going to do before you actually do it. This tutorial assumes that your software does not have any previously registered options or settings, so we will have to register the settings you want to use. After that, you will need to create a space for the form needed to modify the settings, so we will register the page within the admin menu.

Register the Settings

Registering a setting is similar to adding an option, but with an added component. The function that needs to be called is register_setting(). It’s usage is simple once you understand the different parts of a setting. Each setting belongs to a group, which identifies settings with similar goals or in similar areas. For example, your options page has three sections: General, Appearance, and Other. Settings that belong to the “General” section should be grouped together, and might determine if certain basic functions are enabled. The settings that determine how the software’s output look should be grouped together in “Appearance.” Finally, any remaining settings would be placed into the “Other” group.

To actually register a setting, you need to know which group it will belong to and what to name it. Once you know those two pieces of information, you can create your settings using code similar to the example below. Of course, be sure to use your software’s namespace when creating functions and settings. For the following examples, “wphub” will serve as the namespace.

function wphub_register_settings() {
	add_option( 'wphub_use_api', '1');
	add_option( 'wphub_api_callback', 'alpha');
	register_setting( 'default', 'wphub_use_api' ); 
	register_setting( 'default', 'wphub_api_callback' ); 
} 
add_action( 'admin_init', 'wphub_register_settings' );

Imagine that the previous example was to add and register settings that controlled a function that accessed a remote API and processed it through some other function. The

add_option()

function creates the database entry and saves the default value to the database if the option did not already exist. The

register_setting()

function accepts the setting’s group as the first argument, the “default” group for this example, and the setting’s name as the second argument. The group is left as the default group in the previous example due to the added simplicity, and you can research add_settings_section() and add_settings_field() if you need something more complex. If you need to sanitize the information that will be input by the end user, you can provide the sanitizing function’s name as a third argument, and it can be either a custom function or a built-in function. You can create as many settings in as many groups as you need using this method.

Register the Page

Registering your software’s options page is very simple. Just use the code from the example below and paste it into the same file where you registered the settings. Within this example, the

add_options_page()

function, which places your options page under the “Settings” menu, can be swapped with another of the add_submenu_page() wrapper functions. Use

add_theme_page()

to place your options page under the “Appearance” menu, and

add_plugins_page()

to place your options page under the “Plugins” menu.

function wphub_register_options_page() {
	add_options_page('Page title', 'Sidebar Text', 'manage_options', 'wphub-options', 'wphub_options_page');
}
add_action('admin_menu', 'wphub_register_options_page');

All of the wrapper functions of add_submenu_page() accept the same arguments. The first argument is the text to be placed within the page’s

<title>

tag, while second argument is the text to be displayed within the sidebar menu, and should be descriptive enough for users to identify it yet short enough to not push against the sides of the sidebar. The third argument is the capability needed for a user to be able to see the options page, and the fourth is the ID you want this page to have. The ID should be unique, so using your software’s namespace will ensure that. The final argument is the name of the function that will display your option’s page content.

Creating the Page and Displaying Settings

Now that you have told WordPress what you are going to do, it is time to actually do it. Since you have all of your settings registered and your options page defined, you can now go forth with actually creating your options page and laying out your settings.

Create the Page

Creating the layout of the page is simple if you want to be simplistic with your page. There are more advanced ways of executing this, but this shall suffice for what we want to accomplish. The following example demonstrates the basics needed to get your options page functional and displaying content. When using the following code, be sure to replace the page title, optional section title, and descriptive text with your own content. If you wish to include additional sections, just copy everything between

<?php settings_fields( 'default' ); ?>

and

<?php submit_button(); ?>

and paste directly below the material you just copied.

function wphub_options_page() {
	?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>Your Options Page Title</h2>
	<form method="post" action="options.php"> 
		<?php settings_fields( 'default' ); ?>
		<h3>Optional section title</h3>
			<p>Some descriptive text.</p>
			<!-- Form tables go here -->
		<?php submit_button(); ?>
	</form>
</div>
<?php
}

There a few items in the previous example to note. The first is that your options page much be wrapper in a div tag with the class of “wrap,” so that the default CSS can be applied to it. You could remove it if you had something more sophisticated in mind and this tag was interfering with your styles. The second is that you can put any information before or after the form, and you can even completely exclude the form if you are just displaying information. The third and final item to note is that WordPress automatically processes and saves the information entered into form fields as long as you called

settings_fields()

for each setting group you created earlier. This means that you do not need to create a separate function to save the information. All you would do if you wanted information saved in a precise way is to have WordPress pass each setting into a sanitizing function that would then alter the form data into something your software can process.

Display the Settings

Without delving into the more-complicated setup that requires you to declare sections, fields, and callback functions, there is a method of being able to display each setting as you wish in a simple fashion using tables. Yes, WordPress still uses tables on many pages in order to achieve a consistent look across all browsers. The following example should be a template for your own software, and should be located in place of

<!-- Settings go here -->

in the previous example.

<table class="form-table">
	<tr valign="top">
		<th scope="row"><label for="wphub_use_api">Use Remote API?</label></th>
		<td><input type="text" id="wphub_use_api" name="wphub_use_api" value="<?php echo get_option('wphub_use_api'); ?>" /></td>
	</tr>
	<tr valign="top">
		<th scope="row"><label for="wphub_api_callback">API Filter</label></th>
		<td><input type="text" id="wphub_api_callback" name="wphub_api_callback" value="<?php echo get_option('wphub_api_callback'); ?>" /></td>
	</tr>
</table>

This example illustrates two simple input fields, but you may use any type of form field that you require for your software. Be sure to place the same identifier you used in the

register_setting()

in the label’s “for” attribute, and the input field’s “id” and “name” attribute, and well as inside the

get_option()

function.

All Together

If you would like a combined example of everything above, you can copy and paste the following code into your own software.

<?php
function wphub_register_settings() {
	add_option( 'wphub_use_api', '1');
	add_option( 'wphub_api_callback', 'alpha');
	register_setting( 'default', 'wphub_use_api' ); 
	register_setting( 'default', 'wphub_api_callback' ); 
} 
add_action( 'admin_init', 'wphub_register_settings' );
 
function wphub_register_options_page() {
	add_options_page('Page title', 'Sidebar Text', 'manage_options', 'wphub-options', 'wphub_options_page');
}
add_action('admin_menu', 'wphub_register_options_page');
 
function wphub_options_page() {
	?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>Your Options Page Title</h2>
	<form method="post" action="options.php"> 
		<?php settings_fields( 'default' ); ?>
		<h3>Optional section title</h3>
			<p>Some descriptive text.</p>
			<table class="form-table">
				<tr valign="top">
					<th scope="row"><label for="wphub_use_api">Use Remote API?</label></th>
					<td><input type="text" id="wphub_use_api" name="wphub_use_api" value="<?php echo get_option('wphub_use_api'); ?>" /></td>
				</tr>
				<tr valign="top">
					<th scope="row"><label for="wphub_api_callback">API Filter</label></th>
					<td><input type="text" id="wphub_api_callback" name="wphub_api_callback" value="<?php echo get_option('wphub_api_callback'); ?>" /></td>
				</tr>
			</table>
		<?php submit_button(); ?>
	</form>
</div>
<?php
}
?>

Summary

A simple options page for your software is not difficult to set up if you only have a few configurable options. Retrieving those options is even easier by using the

get_option()

function. The customization allows your end users to tweak your software to fit their needs, which is highly appreciated by the users and great for the WordPress community. While this tutorial does not utilize the latest features of WordPress to accomplish what we set out to do, it is sufficient for beginner developers creating a simple options page.

Resources

− Link: Administration Menus in the WordPress Codex
− Link: Creating Options Pages in the WordPress Codex

)
Codeable info

Comments (7)

Comment by John says:

I’m using Easy Options Page plugin http://wordpress.org/plugins/easy-options-page/ It’s easy to use, and include image uploads. Nice!

Comment by joki says:

Good one, but if you dont have much time, you can just install the easy options page plugin that allows you to create images, and gives you shortcodes. http://wordpress.org/plugins/easy-options-page/ ;)

Comment by Hardeep Asrani says:

Hey Chris,

Thanks for helping me last time. I need one more help this time. Can you tell me how I can use fields in this option page.

Thanks!

Comment by Chris Ellison says:

If you’re talking about retrieving an option for use in your plugin, this is how:
<php $use_api = get_option(‘wphub_use_api’); ?>

Once you have the option’s value within a variable, you can use it as a normal PHP variable, such as in this example:
<php
$use_api = get_option(‘wphub_use_api’);
if( !empty($use_api) ) {
echo ‘The user entered this: ‘ . $use_api;
}
?>

Comment by Chris Ellison says:

If you’re talking about retrieving an option for use in your plugin, this is how:


Once you have the option’s value within a variable, you can use it as a normal PHP variable, such as in this example:

Comment by Hardeep Asrani says:

Okay,

So this is how we create options pages. I created a simple plugin & can you explain me how to use option & plugin together. I don’t get it how to replace plugin code values with option page setting.

Thanks… :)

Comment by Steven says:

Simple and fast load options page. Great tutorial Chris

Codeable info