How To Create A Custom Administration Pages in WordPress Dashboard

When WordPress unveiled what used to be its standard theme, Kubrick, several years ago, it also took the wraps of an exciting new feature. That feature was the custom theme administration panel, enabled by defining functions and preferences in the theme-specific “functions.php” file. In the years that have ensued, the theme options page has been sadly underused by many theme designers, but it’s actually a great way to give users control over their site’s appearance without forcing them to install a new theme. THings like the theme background image, number of columns, and even font colors can all be changed using this custom administration panel.

The administration panel itself is changed by filling the theme’s functions file with a series of PHP arrays that define custom values. Those values are then included in the template and they are defined in an administration panel that allows users to define their appearance preferences visually. The whole process is actually relatively simple once the theme designer learns how a PHP works and how they can leverage that piece of code to allow custom presentation within their template files.

The several-step process all begins by setting a few site wide variables and defining what should be customized in this new administration page.

Step 1: Creating and Editing the Theme-Specific Functions.php Page

If you’ve developed your own theme, chances are pretty slim that you’ve made a functions.php file to be paired with the existing template files. This is a relatively advanced options and most designers simply skip it altogether. In this case, it’s essential to open your FTP client of choice and point it to the following server URL where the theme’s files reside:

/public_html/wp-content/themes/YOUR-THEME-FOLDER/

Once inside this folder, double check to make sure there’s no “functions.php” file present and then use your text editing program to create a new file named “functions.php.” This file can then be saved and uploaded to the server via FTP. It can be edited directly on the server, eliminating the need for the text editing program.

The first step to having a valid theme options panel defined in the “functions.php” file is to define two variables at the top of the document. These variables will be used to display the theme’s name using the Dashboard, as well as identify form and selection elements within that administration page. Observe the code below, place it into the top of your “functions.php” document, and customize it to your site’s needs.

$longname = “Administration Panel Development Theme”;
$shortcode = “apdt”;

These variables serve different purposes. The $longname variable will be used to print the theme’s name in the actual administration options panel. For this reason, it is recommended that developers assign the theme’s exact name to this variable in order to eliminate confusion among their theme’s users. The $shortcode variable should be all lowercase letters without any punctuation, as this will be used to identify form elements within the code itself. In the example, a simple acronym was used based on the theme’s full name; this can be customized to a user’s tastes.

Step 2: Defining Customizable Preferences Using PHP Arrays

First, it’s important to tell the theme what the administration panel’s name is. This will be printed above all of the potential settings and helps foster clarity of purpose to novice users. This is done by adding the following array to the $settings tag within the “functions.php” file:

$settings = array (
array( “name” => $longname.” Appearance Settings”,
“type” => “title”),

Next, we must indicate that the array full of options is “open,” or able to be modified by user input. This is done using another simple array that appears right below the definition of the page’s title. It looks like this:

array( “type” => “open”),

Now we are free to begin defining theme appearance options, with each one of them being created as a new array. In this example, we’re going to define the text which is placed in the theme’s footer. By default, the example theme contains a link to the theme developer’s website as well as teem versioning information. This is not desirable by a large number of WordPress users who would prefer to place their own information in the footer, however, so enabling this custom control saves them the manual editing of the “footer.php” file. Here’s how it’s done.

array(
“name” => “Custom Theme Footer Text”,
“desc” => “This is the text displayed at the very end of every page contained within this theme.”,
“id” => $shortcode.”_custom_footer”,
“type” => “text”,
“std” => “Experimental Theme v1.0. Developed by John Doe. More themes here.”),

The array above allows the user to determine the theme’s standard footer text, but the array tags need to be explained to better describe just how this process works and what each part of the array defines.

Name: This refers to the name of the actual text box itself, and is not presented to users when they enter the administration options page for the theme.

Desc: This is a short description that accompanies the custom setting, and this is displayed to users.

ID: This uses the short code along with a custom-made identification of the form name in order to both present and style the text box.

Type: This defines whether the form element is a text line, a text box, a drop down menu, a radio button, or a checkbox.

STD: This determines the default value of the selected element. For a text box, this determines the default text entered into it. For checkboxes, radio buttons, and drop down boxes, this determines which option is selected by default.

Step 3: Telling WordPress to Enable Access to the New Options Page

Even though the options page has been given a purpose using the “functions.php” file within a theme’s home folder, it has yet to be recognized by WordPress or included among the many other settings page within the WordPress Dashboard. This is because the theme’s option page must be identified in the functions page and told where to go (either as an independent sidebar element or within the “Settings” grouping). This is done using a relatively simple function which is added to the “functions.php” file below the arrays of potential customizations:

function experimental_theme_save_values() {
global $longname, $shortcode, $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($longname.” Appearance Settings”, “”.$longname.” Appearance Settings”, ‘edit_themes’, basename(__FILE__), ‘experimental_theme_save_values’);

This piece of code does two things. First, it allows the theme’s settings to be saved via the administration options panel. Secondly, it places an independent button in the WordPress Dashboard’s sidebar that allows a user to click it and go directly to theme options panel. It is labeled “Appearance Settings” just like the actual page itself. Consistency is the key to eliminating confusion and directing users to the page without specifically telling them to make their way to the options panel to customize the theme’s appearance.

Step 4: Adding Error Messages and Closing the PHP File

The final step to filling in all the elements of the theme options panel is to define error messages that a user may encounter and then make sure that the form elements can be presented in the default WordPress style within the options page. Adding the error messages is done by pasting this code into the PHP functions file:

function experimental_theme_save_values() {
global $longname, $shortcode, $settings;
if ( $_REQUEST[‘saved’] ) echo ‘
‘.$themename.’ appearance customizations have been saved successfully.
‘;
if ( $_REQUEST[‘reset’] ) echo ‘
‘.$themename.’ appearance customizations have been successfully reset.
‘;

Beneath these two lines of code, the PHP section of the functions.php file can be closed using the ?> ending tag. Below this, XHTML code will be placed to style the elements using the standard WordPress Dashboard stylesheet.

Step 5: Giving the Options Page Some Style

Currently, WordPress Dashboard users can see the new error page but they can’t do much with it. That’s because the form elements and the stylesheet have not yet been placed into the functions.php file for use within the administration interface. That’s all about to change, as we include the stylesheet and default form elements for use by the new panel:

< div class=”wrap” >
< h2>< ?php echo $longname; ? > Settings< /h2 >

< form method=”post” action=”options.php” >

< ?php break; case ‘text’: ? >

< tr>
< td width=”20%” rowspan=”2″ valign=”middle” >< strong >< ?php echo $value[‘name’]; ? >< /strong >< /td >
< td width=”80%” >< input style=”width:100%;” name=”< ?php echo $value[‘id’]; ? >” id=”< ?php echo $value[‘id’]; ? >” type=”< ?php echo $value[‘type’]; ? >” value=”< ?php if ( get_settings( $value[‘id’] ) != “”) { echo get_settings( $value[‘id’] ); } else { echo $value[‘std’]; } ? >” / >< /td >
< /tr >

< tr >
< td >< small >< ?php echo $value[‘desc’]; ? >< /small >< /td >
< /tr >< tr >< td colspan=”2″ > < /td >
< /tr >

< ?php break;} ? >

< input type=”submit” value=”< ?php _e(‘Save Theme Settings’) ? >” / >

This code is pasted below the closing tag of the PHP functions file, and can be customized for each type of form that a theme options panel might include. The “case” variable can be changed from “text” to things like text box, checkbox, select, and title. These forms only need to be included, defined, and styled, if they are being used by the theme. Otherwise, their inclusion is not necessary and leaving then out of the theme’s functions file will promote efficiency and clean code.

Step 9: Enabling the Custom Option to be Seen on the Actual Theme

There are two steps to execute when making sure that any changes can be seen on a theme’s public templates. The first is to place a variable into the theme’s footer which will display the user-defined copyright and versioning text that we enabled in the earlier steps of this tutorial. That is done by placing the following code in the footer copyright area:

< ?php echo $apdt_custom_footer; ? >

This text calls the custom array for the footer text that was defined earlier and, per the “Echo” statement, prints that text in the footer. This tag can be contained within any XHTML tags a user sees fit, but it will not show up without a piece of code added to the site’s header.

In the header, the theme must be instructed to look for the user-defined options that are set within in the WordPress Dashboard, and it must know the variables that are defined in the custom “functions.php” file so it can print their content onto the website. This is done by placing the following PHP variable in the header of the website (typically the “header.php” file):

< ?php global $settings;
foreach ($settings as $value) {
if (get_settings( $value[‘id’] ) === FALSE) { $$value[‘id’] = $value[‘std’]; } else { $$value[‘id’] = get_settings( $value[‘id’] ); }
}
? >

That’s all there is to it. Now, every option defined in the custom functions.php file can be reflected in the page’s appearance simply by including a custom-defined PHP variable where the designated customizations and content are supposed to take effect.

Step 10: Test the New Settings and the Options Page

No WordPress development effort is fully complete until it has been thoroughly tested for bugs, errors, and accidental errors in the PHP code placed into the “functions.php” file. That said, it’s time to get testing! Log in to the WordPress Dashboard and, if the theme you’ve been working on is not currently selected, make sure to navigate to the “Appearance” category in the sidebar and activate the relevant theme.

From there, check a few things:

  1. Make sure the theme’s settings link appears as its own entity in the sidebar underneath the “Settings” sidebar category heading.
  2. Ensure that the designated footer text customization option can be accessed in the custom options control panel; modify the default content of the footer and save the preference. Make sure that it saves without an error.
  3. Visit your actual, public website, and ensure that the changes made within the Dashboard concerning the content of the footer are displayed.
  4. If everything functions properly, breathe a sigh of relief and enjoy your first WordPress theme options control panel page.