Amongst other features, WordPress 2.7 includes numerous improvements around the security and flexibility of user options for third-party themes and plug-ins. I’ve been trying to add an options page to my theme but I couldn’t find any clear, up-to-date advice on how to go about it for this particular version. Here’s how I did it.

I’m going to show you how to create an options page for your theme users that they can access from the Appearance menu in their WordPress 2.7 dashboard. For theme options, this is the traditional, most visible, and hence user-friendly method in my opinion. In this version of WordPress, it is also possible to add custom options to any of the native settings pages, but this is not covered here.

What’s more, we’re going to heed the WordPress team’s warnings about existing option methods being deprecated in future and use the new settings API to make ours forward-compatible and consequently more secure. Hopefully, it will also mean one less thing to fix when the next major version drops.

Finally, we’ll learn how to retrieve these options, but because this has not changed since version 2.6, these are already well-documented elsewhere. There are also so many ways to implement them that we would need at least another post to do them justice.

To write this post, I pieced together the code from the following pages on WordPress.org:

As with earlier versions of WordPress, there are two main steps:

  1. Amend your theme’s functions.php file to automatically generate an options page for your theme users’ dashboard containing the options you specify.
  2. Add code to your other theme files that can make use of the options saved in this page.

Step 1 – creating the options page

Add the options page to the dashboard

Open up the functions.php file in your theme’s folder. If there isn’t one, create it and insert:

<?php
  // paste all the code between these tags
?>

To begin with, we need to tell WordPress to add the options page to the dashboard whenever it is displayed. We can use a native WordPress command to do this. Add this to your functions.php file:

add_action('admin_menu', 'mytheme_menu');

The only thing you can / might want to change is 'mytheme_menu' which will be the name of a function we’ll create now. In 2.6, this would be the page building function, but in 2.7 it will call an intermediate function that adds the new menu placement and security features first.

Register the options you intend to use

Add the following code above the previous line.

function mytheme_menu () {
  add_theme_page (
    'My theme options', 'My theme options',
    8, __FILE__, 'mytheme_options_page');
  register_setting (
    'mytheme_options', 'mytheme_option1', '');
  register_setting (
    'mytheme_options', 'mytheme_option2', '');
}

Here, because we are using 'add_theme_page', our options page is positioned in the Appearance menu – alternatives are available. Then, the options are registered for security. You can add more of these if you wish. If you changed 'mytheme_menu' in the first line of code, make sure you change the name of this function accordingly. For more explanation about the variables, search around, but for now here are the ones you need to know about:

The two ‘mytheme_option’ values are the title of your new options menu item and options page in the dashboard. The 'mytheme_options_page' value is the name of the function we are about to create that will build your options page. The 'mytheme_options' value is the group name for your options, which in this example are named 'mytheme_option1' and 'mytheme_option2'. They don’t have to be numbered sequentially or anything, just named differently. The variables after these option names can contain default values, but we’ll leave them blank.

Create the options page

Now we’ll add the function that builds the page. It’s based on the code supplied for 2.6 (at time of writing) on this page, but it’s a bit simpler. Again, paste it in above the code you’ve added so far.

function mytheme_options_page () { ?>
  <div class="wrap">
  <h2>My theme options</h2>
  <form method="post" action="options.php">
  <table class="form-table">
  <tr valign="top">
  <th scope="row">My theme's first option</th>
  <td><input type="text" name="mytheme_option1"
    value="<?php
      echo get_option('mytheme_option1'); ?>" /></td>
  </tr>
  <tr valign="top">
  <th scope="row">My theme's second option</th>
  <td><input type="text" name="mytheme_option2"
    value="<?php
      echo get_option('mytheme_option2'); ?>" /></td>
  </tr>
  </table>
  <?php settings_fields('mytheme_options'); ?>
  <p class="submit">
  <input type="submit" class="button-primary"
    value="<?php _e('Save Changes') ?>" />
  </p>
  </form>
  </div>
<?php }

If you know your HTML, most of this will make sense, and you’ll be able to remove the line breaks I added to fit my blog. If not, don’t worry, there’s actually very little you have to change here. Aside from the function name at the top, there’s the name="mytheme_option1" attribute in each input tag to change along with the accompanying php echo get_option('mytheme_option1'), which retrieves the value if it already exists.

If you’re using more options, select all the code from <tr valign="top"> to the </tr> and copy it as many times as you need. Don’t forget to change the name of each option and register them in the other function. Please note that you aren’t limited to text fields – you should be able to track down instructions for adding checkboxes and dropdown menus, etc.

Then, save and upload your functions.php file and log in to the dashboard to check out your new options page! Enter some values, save them and let’s get on with the second step: retrieving them.

Step 2 – retrieving your options

This is the easy part, because you’ve already encountered the command that retrieves your option values in the preceding code for the options page.

get_option('mytheme_option1');

There seems to be plenty of advice on the web about how to implement your options once you have retrieved them, so I’ll leave you with the most basic example I can think of. Let’s assume mytheme_option1 contains a colour value (eg #336699) that you wish to apply to an HTML div container in one of your theme files.

<div id="header" style="background-color:
  <?php echo get_option('mytheme_option1'); ?>;">

Conclusion

There. We’ve got our theme options page set up in the dashboard, have registered our options for security and forwards-compatibility, and can retrieve those values elsewhere in our theme. I’ll leave you to work out how to add different form elements to your options page and how best to implement its values in your theme.