How to Create a WordPress Custom Options Page

In this detailed tutorial we show you how to create a WordPress custom options page within the functions.php file.

Options pages are as easy to use as any other control panel page within the Dashboard, but they’re advanced and flexible enough to allow the user to control every detail of their installed theme, at least as long as the ability has been defined as a user-customizable setting. Here we go…

Building a WordPress Custom Options Page

Step 1: Open the functions.php File

When beginning the process of adding a custom preferences panel to an existing WordPress theme, you will need to navigate to that theme’s root directory (often contained within the “wp-content” directory if the theme has been uploaded to a WordPress installation).

Once this file has been located, download it to the desktop and open it in a text editor; alternatively, it can be edited directly on the server using the FTP client’s built-in file and text editing application. This is probably the best option for most developers, as it allows them to directly save the file without managing multiple versions of it.

Step 2: Defining Variables for Use Within the Preferences Page

A good control panel page must make good use of variables, and in this case two of them will be used extensively throughout the code. The first variable is the $theme variable, which will actually define the name of the theme itself. This will be used throughout the code rather than hardcoding the theme’s name every time it must be used. It leads to more efficient code and it helps the settings page become a little easier to adapt to multiple themes if a developer wishes to update their themes across the board with custom control panel pages.

The second variable used throughout the custom control panel preferences page will be the $form variable.This is a short, two or three-letter variable which will be appended to every XHTML form element that is placed on the control panel page itself. Not only does this distinguish the page’s form elements from those on other pages within the Dashboard, but it also helps the WordPress database know which settings to write to the database and where to save those settings so that they are properly reflected on the production page after they have been successfully saved or reset within the Dashboard.

When those two variables are added to the theme-specific functions.php file, they look like the following example:

$theme = "A Theme with Customizable Preferences";
$form = "atc";

Remember that the $theme variable should match exactly with the name of the theme itself. Users like to see continuity between all pages within the Dashboard, and placing a different name in the control panel page than users see within the “Appearance” page would lead to a bit of dissonance that might prevent them from taking advantage of the preferences listed here.

Step 3: Using PHP Arrays to Define the Custom Preferences

The first step to creating a full preferences page within the WordPress Dashboard is to simply create a PHP array and declare it open. An open array is read by the Dashboard and each setting is placed into a functioning preference page using a function which will be added later. First, we must open the array and tell it what to name the new control panel page. Because we’ve already used the $theme variable to define the theme’s name, we can simply use this and a little extra text to give the page a descriptive title within the PHP array. Here’s how it’s done:

array (
array( "name" = > $theme." Preferences",
"type" = > "title"),
array( "type" = > "open"),

That gives the page a title which will be displayed both on the page itself and in the browser title bar when the preferences page is being viewed by the theme user. Below the array which defines the page’s title, a new array called “open” is listed. This serves to tell the control panel that everything beneath the title element should be parsed as a setting, and it will be done as instructed using the function which will be placed into the functions.php file after the array. Following this tag, we must now define the settings that a user can modify on their own.

Step 4: Creating User-Defined Settings for the Preferences Page

Every setting that a user can define on their own is placed into the functions.php file using an array that is setup the exact same way every time. This array is pretty basic, and each one will serve to label the preference element, describe it, set the options a user can select, and set a “default” option that is selected up on first loading the new settings page. The array uses the same variables over and over again, and a sample preference looks like this example:

array( "name" = > "Sidebar Position",
"desc" = > "This setting can determine the position of the website's sidebar on the fly, placing it either to the left or right of the site's main content area depending on the user's preferences. No changes are required to be made to the stylesheet or theme template files.",
"id" = > $form."_sidebar_xy",
"type" = > "select",
"options" = > array("Left, Right"),
"std" = > "Right"),

In the example above, it’s pretty self-evident how a setting is created. It’s worth noting that, while all of these fields must be filled out the same way each time, there is at least one variable within the array which must be changed by the developer. That is the “type” element, which can be set to display things like text boxes, checkboxes, or drop-down boxes depending on developer preference. Remember that the corresponding “options” and “std” elements will need to be changed if the “type” element is altered as well.

Once all of the arrays have been added to define the settings which a user can manipulate, it’s time to close the arrays so that the PHP functions file knows to move on to the next step of the process in creating this page. That’s done by adding yet another array, although this one is only one line:

array( "type" = > "close"));

The array is now closed, and developers can move on to adding traditional functions to the file. These functions, combined, add the control panel page to the sidebar and database, and define input validation messages when a user saves the relevant settings.

Step 5: The Functions Which Turn an Array into a Control Panel Page

WordPress must now be told that the arrays at the top of the functions.php file actual serve as options for a control panel page. This is done by adding a function to the Dashboard through the existing file. This function is added directly below the arrays:

function theme_settings() {
global $theme, $form, $settings;
if ( $_GET['page'] == basename(__FILE__) ) {
if ( 'save' == $_REQUEST['action'] ) {
foreach ($settings as $value) {
update_option( $value['id'], $_REQUEST[ $value['id'] ] ); }
foreach ($settings as $value) {
if( isset( $_REQUEST[ $value['id'] ] ) ) { update_option( $value['id'], $_REQUEST[ $value['id'] ] ); } else { delete_option( $value['id'] ); } }
header("Location: themes.php?page=functions.php&saved=true");
die;
} else if( 'reset' == $_REQUEST['action'] ) {
foreach ($settings as $value) {
delete_option( $value['id'] ); }
header("Location: themes.php?page=functions.php&reset=true");
die; } }
add_menu_page($theme." Preferences", "".$theme." Options", 'edit_themes', basename(__FILE__), 'theme_settings_admin');
}

function theme_settings_admin() {
global $theme, $form, $settings;
if ( $_REQUEST['saved'] ) echo '< div id="message" >'.$theme.' settings are saved.< /div >';
if ( $_REQUEST['reset'] ) echo '< div id="message" >'.$theme.' settings are reset.< /div >';

That’s all there is to it. Essentially, the PHP part of this tutorial is now over. What remains is simply adding the XHTML display elements to the Dashboard control panel page itself. That’s relatively easy, especially for a seasoned WordPress developer and coder.

Step 6: Adding Display Elements

When a custom control panel is created, the developer must add all of the XHTML form elements (such as text area tags, submit and reset buttons, and other information) manually to the functions.php file. This is pretty straightforward, as the elements need only be created in the most basic sense. Everything else is added to the XHTML tags by the PHP function, and the form elements will be styled by the Dashboard stylesheet. Of course, the stylesheet can only be put to use if the following tag surrounds all of the XHTML elements in functions.php file:

<div class="wrap">

Don’t forget to also provide a </div> tag after the last XHTML form element created. When that’s been done, there is just one more step within the actual functions.php file to make sure that the entire thing works as planned.

Step 7: Instructing the Dashboard to Place a Control Panel Link into the Sidebar Area

Earlier in this tutorial, a function was created which allows the Dashboard to show a link to the custom control panel within the sidebar. However, because no “action” was added during that time, the link is not yet visible to the end user. At the end of the functions.php file, simply place the following line of code to ensure that the control panel is accessible via the Dashboard sidebar:

<?php } add_action('admin_menu', 'theme_settings_admin'); ?>

Now, save and close the file. When it is uploaded to the server, simply navigate to the Dashboard and ensure that the new control panel link appears in the sidebar. Click that link, manipulate some settings, and save them. Ensure that the differences are reflected in the activated theme and that there are no error messages during or after submission. If that’s the case, then the process is complete and the control panel is ready to give a WordPress theme a new lease on life.

Author: (40 Posts)

Vladislav Davidzon is the principal of US-based online marketing consultancy Vladislav Davidzon & Associates, developing integrative solutions through high impact search engine optimized WordPress websites for socially responsible customers of all sizes around the world.

Comments