How to Create Custom Settings Pages for WordPress Themes
A number of widely-distributed WordPress themes include a custom control panel that allows users to set several key display preferences without editing any of the themes actual PHP template files. This approach makes sense, as the average WordPress user is, by definition, a blogging and web designing novice. Allowing point-and-click customization of a theme improves its usefulness to those who download it and it ensures that the theme is in use longer, on average, by those users who can more easily customize the way it appears to their readers. It all adds up to good news for theme developers whose work, and a link to their wider gallery of themes, is included with the theme.
It might seem like a daunting task or one which is needless complex, but generating a WordPress theme options page is actually a simple process that involves a little CSS, some WordPress variables, and PHP arrays within the WordPress functions file. For the enterprising WordPress theme developer, here's how to give a theme a life of its own with a customized options page accessible by the average user.
Step 1: Creating and Editing the Correct Functions.php File
Any seasoned WordPress plugin or theme developer knows that the content management solution relies on two separate "functions.php" files to dictate, well, the software's functions. The most important of these is the main "functions.php" file which is located in the "wp-includes" directory within the WordPress root folder. This file contains all of the essential functions that WordPress does on a daily basis, from posting entries to producing content in the famous WordPress Loop. This file should not be edited during this process.
Instead, a theme-based options panel in the WordPress Dashboard is created using the theme-specific "functions.php" file which is found within the theme's home directory. It might seem a bit counterintuitive, especially since every other control panel is generated with the other functions file, but it's a simple rule to follow when generating a theme preferences pane. With this knowledge in hand, open up your FTP client of choice and navigate to the theme which will receive a new customized control panel for its appearance settings.
If a "functions.php" file already exists in this directory, open it. More than likely, however, a custom-developed theme will lack such a file. In this case, open a text editor and create a blank document named "functions.php" (this much should be obvious). Then upload this file to the directory and begin editing it directly using the FTP client instead of the text editor. This will ensure that all changes are saved directly to the website' server, rather than to the user's computer, and will prevent confusion later on.
Step 2: Define Variables Used Within the New Options Panel
The first step of the actual coding process involves setting two new variables which will be used to name the options page and identify the user-designated forms and checkboxes that will reside on it. Place a small snippet of code at the top of the file which looks like the following:
$formid = "twcp"; $themetitle = "Theme With Control Panel";
The names above aren't very original, so feel free to customize both the theme's name in the $themetitle variable as well as its shorter acronym for use when identifying forms using the $formid variable above it. When those have been filled out, it's time to move on to the more involved part of the process.
Step 3: Defining the Options that a User Can Customize
The point of this theme control panel is to allow a user to customize certain aspects of a theme's appearance with just the click of a mouse. It's now time to determine exactly which setting they can customize using the theme's new options panel, and this will be done using the popular PHP "array" method of defining options and settings. In this example, we're going to allow the user to choose between three different images for the site's masthead area. This will appear in a drop-down selection box and they'll save their settings using a submit button.
Before we begin, it's time to give the new options page an appropriate title. This, too, is done using an array. Keep it simple, brief, and relevant to the tasks being performed:
array( "name" => $themetitle." Custom Apperance Settings", "type" => "title"), array( "type" => "open"),
This is pretty straightforward: It prints the theme's name as defined in the $themetitle variable and then appends "Custom Appearance Settings" to the theme's title. That gives a pretty idea of what's going on via the forms presented on this page. Users will know that they're here to make visual customizations and nothing else. Simplicity is good.
Next, we're going to use a PHP array to define the options for the theme's drop-down box. This will allow the user to select one of several different header images for the theme's masthead.
array( "name" => "Theme Masthead Image",
"desc" => "Choose from one of three images to use in your WordPress site's header.",
"id" => $formid."_masthead_image",
"type" => "select",
"options" => array("Beach", "Forest", "Highway"),
"std" => "Highway"),
The array above is pretty simple to understand, but it's worth explaining each of the variables presented so that they can be manipulated for further customizations in more complex theme options page setups. First and foremost, the array needs a descriptive and unique name. In this case, it has been designated the "Theme Masthead Image" array using the "desc" variable.
The "id" variable is used to determine the ID of the form as well as the database table which will be created to store the user's preference upon selecting one of the three available options. Next, the "type" control determines whether the option is presented on as one-line text box, a multi-line text box, a checkbox, or a drop-down menu. In this case, we've used "select" to indicate that a drop-down menu is the appropriate method of setting the preference.
Next, the "options" operator determines how many options will be presented to the user and what they'll be called. Options can be one word or many words, and will appear within the drop-down box itself. This operator is only useful with drop-down boxes and checkboxes. It will not be valid for text boxes.
Finally, the "std" operator (which is short for "standard") determines which of the available options is selected by default. This can be changed according to a designer's needs and requirements. And that's really all there is to it, as far as the array-generating process is concerned in a custom options page.
Step 3: Bringing the Array onto an Actual WordPress Options Page
With the options having been set in the previous step, it's now time to add the next piece of code to the "functions.php" file. This code will display a link to the settings in the Dashboard and it will place that link under the "Appearance" tab in the sidebar. It will allow setting sot be pulled from, and written to, the site's database. It's pretty complex in nature and it looks like this for the drop-down menu:
function option_page_settings() {
global $themetitle, $formid, $prefs;
if ( $_GET['page'] == basename(__FILE__) ) {
if ( 'save' == $_REQUEST['action'] ) {
foreach ($options as $value) {
update_option( $value['id'], $_REQUEST[ $value['id'] ] ); }
foreach ($options 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 ($options as $value) {
delete_option( $value['id'] ); }
header("Location: themes.php?page=functions.php&reset=true");
die;}}
add_theme_page($themename." Custom Appearance Settings", "".$themename." Custom Appearance Settings", 'edit_themes', basename(__FILE__), 'option_page_settings');
}
This function is rather standard, but there is one area for customization at the bottom. The theme's administration page is currently displayed under the "Appearance" tab because we've used the "add_theme_page" function. For users who prefer that a link be created in the sidebar which is its own category, not nested below any parent, this can be changed to "add_admin_page." It's a matter of personal preference, so feel free to change this.
Step 4: Adding Status Messages
Next, it's time to tell the theme what to print on the site after a user has saved their settings or reset them to the default options defined in the array that was coded earlier. This goes in the functions file and it looks like the following simple setup:
function mytheme_admin() {
global $themename, $shortname, $options;
if ( $_REQUEST['saved'] ) echo '< div class="options-message" >'.$themename.' custom appearance options were saved.</div>';
if ( $_REQUEST['reset'] ) echo '< div class="options-message" >'.$themename.' custom appearance options were reset.</div>';
Step 5: Adding Form Selection Elements to the Functions.php File for End-User Display
Everything is in place for the new theme options page, but there is still an important aspect of the new panel which is missing: the actual form elements for choosing settings. These are styled by the WordPress Dashboard stylesheet so long as they are enclosed with the < div id="wrap > tag. Within this wrap tag, the user must define options for every kind of form element. This is done by placing them between PHP conditional variables that look like the following:
< ?php foreach ($prefs as $value) { switch ( $value['type'] ) { case "text": ? >
[ XHTML Text Box Elements ]
< ?php break;? >
Each form element is styled in between its own conditional PHP tags. Where the current variable lists "case 'text'", designers can substitute checkbox, select, title, and textarea. How these forms are contracted or displayed is entirely up to the designer, but they'd be well advised to create an options page that blends with the existing WordPress setup.
Step 6: Telling WordPress to Add the Options Page Shortcut
In a previous step, it was determined whether WordPress would display a direct link to the theme or nest it beneath one of the categories in the sidebar. This did not, however, tell WordPress to actively echo the choice onto the Dashboard's sidebar itself. Before closing the functions.php file and rejoicing in the creation of your first theme options page, the following code must be added into the theme's "functions.php" page after the closing ?> PHP tag:
< ?php } add_action('admin_menu', 'option_page_settings'); ? >
This will place a link to the theme's options page in the location designated by the user in that earlier step, and the process will be complete. Make sure that there are no bugs, and that the form elements are styled appropriately, and then enjoy this new step in your development as a near-professional WordPress theme designer!
