Cheesetoast

Brain Food for Web Developers

A custom theme menu under the 'Appearance' tab of the Wordpress admin area

Add Custom Theme Options to WordPress Admin Menu

A custom theme menu under the 'Appearance' tab of the WordPress admin areaLearn how to add your custom options page to one of the existing WordPress admin menus.

In this example I’ll demonstrate how to create a simple options page that allows the user to add a telephone number which will be displayed on a theme.

Creating an options.php file

Although it’s possible to add the necessary code to your functions.php file, it’s considered good practice to keep your menu code in a separate file. This is especially true if you’re adding lots of options, since it keeps your code organized.

Create a new PHP file and name it options.php. You can either save it in your theme’s root directory ([Wordpress root] > wp-content > themes > [current theme]) or, if you have other important theme files, you can create a sub-folder called ‘library’ and save it there.

Now we need to make sure this new file is called by including the options in your functions.php file. Open up your functions file (located in [Wordpress root] > wp-content > themes > [current theme] > functions.php) and add the following code:

require_once ( get_template_directory() . '/library/options.php' );

Or if you’re using a child theme:

require_once ( get_stylesheet_directory() . '/library/options.php' );

Now you can populate your options.php file and it will be included by WordPress.

Writing your options.php file

Adding an options menu involves 3 main steps:

  1. Create a function that tells WordPress to build a new menu item.
  2. Register the function using a ‘hook’.
  3. Create a function that displays the contents of the options page.

1. Create the function that builds your menu

This step is fairly simple but very important. This is the function we’re going to use:

function add_custom_theme_options()  
{  
    add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function );  
}

The add_theme_page function will add our options page as a sub-menu to the ‘Appearance’ main menu. Here are the parameters for that function:

$page_title
The HTML title tag of the page.
$menu_title
The title of the page as displayed in the menu.
$capability
Used to determine which role the user requires to be able to use the menu.
$menu_slug
A unique name for this menu item.
$function
The name of the function called on to display the HTML code for your options.

Here is an example of the function is use:

function add_custom_theme_options()  
{  
    add_theme_page('Theme Options', 'Theme Options', 'manage_options', 'custom_options_slug','custom_theme_options');  
}

Read more about the add_theme_page() function.

2. Register the function

Now that we have our menu-creating function we need to add it to WordPress using a hook. Just add the following code:

add_action('admin_menu', 'add_custom_theme_options');

3. Create a function that displays the contents of the options page

We’re going to write the HTML code for the options page and put it in a function. This function is the one we called in step 2 so make sure you use the same name (in this case ‘add_custom_theme_options’).

function add_custom_theme_options()
{  
if ( !current_user_can( 'manage_options' ) )  {
	wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}
?>
<div class="wrap">
<h2>Theme Options</h2>
<form method="post" action="options.php">
<?php wp_nonce_field('update-options'); // Security - used to validate source.
<p><strong>Tel No:</strong><br />
<input type="text" name="telno" size="15" value="<?php echo get_option('telno'); ?>" />
</p>
<p><input type="submit" name="Submit" value="Save Options" /></p>
<input type="hidden" name="action" value="update" />
<input type="hidden" name="page_options" value="telno" />
</form>
</div>
<?php } ?>

Now when you look in your admin area you’ll see your new sub-menu titled ‘Theme Options’ under the ‘Appearance’ menu. In the new options page you’ll see the form that we just wrote. You can use it to save the telephone number to the WordPress database.

Using the new options in your theme

Now that we have the telephone number saved we can use it in the theme.

<?php if (get_option('telno')){ ?>
<div id="telno">
<p>Tel: <?php echo get_option('telno'); ?></p>
</div>
<?php } ?>

If the telephone number has been saved in the options page then it will display it in the theme. Otherwise it will be left blank.

For more information on adding custom menus read the WordPress Codex.

Author: Graham

My name is Graham and I'm a Scottish web developer living in California. I love working with clean code to make attractive and usable websites. I'm also interested in cooking, gardening, and taekwondo.

Comments are closed.