Theme Options Pages in WordPress

When developing WordPress themes, you can open a portion of your code for user-customisation on a Theme Options page. This is how it’s done.

The basics of Theme Options is that you can create an options array to store a certain amount of data, then whilst developing your theme, you can account for these changes.

Adding A Theme Options Menu Item

On a Theme that has Theme Options available, you are able to hover over ‘Appearance’ and see additional entries. Here’s an example:

The menu item doesn’t necessarily have to say Theme Options; the Twenty Ten theme has two options; ‘Header’ and ‘Background’.

The first thing that you need to do is create a ‘theme-options.php’ in your theme directory (it can be named whatever you choose really, but I’ll be using theme-options.php thoughout).
Then at the very top of your functions.php file, add this line.

require_once ( get_stylesheet_directory() . '/theme-options.php' );

1	require_once ( get_stylesheet_directory() . '/theme-options.php' );

This tells your functions.php file to include whatever is in the theme-options.php file. I like to keep the theme options separate for clarity.

Now open theme-options.php and add this:

add_action('admin_menu', 'theme_options_add_menu_item');

function theme_options_menu_item() {
    add_theme_page('Theme Options', 'Theme Options', 'edit_theme_options', 'theme_options', 'theme_options_build_page');
}

add_action('admin_menu', 'theme_options_add_menu_item');

function theme_options_menu_item() {

add_theme_page('Theme Options', 'Theme Options', 'edit_theme_options', 'theme_options', 'theme_options_build_page');

}

The basics of the above area, is creating a function to run on the ‘admin_menu’ pre-defined function.
Within this function we can add our menu item.

In the ‘add_theme_page’ function the arguments are as follows:

Page Title – this is the full title of the page
Menu Title – usually the same, but can be an abbreviated version
Capability – this is for administrative permissions. “edit_theme_options” means that anybody who is allowed to change theme options, can access this menu item.
Slug – simple, the menu slug.
Function – the function you wish to execute when the menu is clicked.

We’ll be looking deeper into ‘theme_options_build_page’ soon.

Setting Up the Theme Options array

The theme options array is the way in which your theme options are stored in the database. This impacts how Theme Options are stored, how they’re accessed on the Theme Options page and how they’re accessed through the front-end.

We need to add another action now, but this time we want to attach a function to the ‘admin_init’ action – so it runs automatically when admin pages are accessed.

add_action('admin_init', 'theme_options_init');

function theme_options_init() {
    register_setting('my_options', 'my_theme_options', 'theme_options_validate');
}

add_action('admin_init', 'theme_options_init');

function theme_options_init() {

register_setting('my_options', 'my_theme_options', 'theme_options_validate');

}

Normally, when you register a setting, you do it on an individual option by option basis. However, I prefer to create all options under an array, so I can access them all with one call if I want to.

In the ‘register_setting’ function the arguments are as follows:

Group Name – this is what you’re calling your options. You give them a unique name so you can make multiple groups if necessary
Options Name – this is the name of your option. In my case, the name of the array
Sanitise Function – this is a function you will create (or utilise) to prepare your data for database submission. More information on sanitisation.

I’ve created a function to sanitise the Theme Options data.
This function will be specific to whatever options you choose to make available, but I’ll add mine to the end of this post so you can see how I’ve handled it.

At this stage, we can access a ‘Theme Options’ menu item and modify a ‘my_theme_options’ array which will hold all my data.

The Theme Options Form

We now add a HTML form to the ‘theme_options_build_page’ that we mentioned earlier.

This HTML form will allow our admin user to directly access the variables we want them to.

function theme_options_build_page() {

}

function theme_options_build_page() {

}

Everything contained in the above function will be executed when our menu item ‘Theme Options’ is pressed.

We can create any sort of HTML form here, though I like to keep it matching the familiar WordPress feel, so I like to use their pre-defined elements.

if (!isset($_REQUEST['settings-updated']))
    $_REQUEST['settings-updated'] = false;
?>
<div class="wrap">
    <?php
    screen_icon();
    echo "<h2>" . get_current_theme() . 'Theme Options' . "</h2>";
    ?>

    <?php if (false !== $_REQUEST['settings-updated']) : ?>
        <div class="updated fade"><p><strong><?php echo 'Options saved'; ?></strong></p></div>
    <?php endif; ?>

    [FORM GOES HERE]
</div>

if (!isset($_REQUEST['settings-updated']))

$_REQUEST['settings-updated'] = false;

<?php

screen_icon();

echo "<h2>" . get_current_theme() . 'Theme Options' . "</h2>";

<?php if (false !== $_REQUEST['settings-updated']) : ?>

<?php endif; ?>

[FORM GOES HERE]

</div>

Above is the initial setup for the form. First we need to access a variable called settings-updated which is the variable that WordPress uses to generate the neat little ‘Options Saved’ message boxes.

The above code opens a div called “wrap” which is styled by WordPress, and places into it a page title, ‘settings updated’ div (also styled by WordPress) and your form.

I want to allow two changes, a ‘Primary Colour’ and a ‘Header URL’.

Here is my form:

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

            <?php settings_fields('my_options'); ?>
            <?php $options = get_option('my_theme_options'); ?>

            <table class="form-table">

                <tr valign="top">
                    <th scope="row"><?php echo 'Primary Colour'; ?></th>
                    <td>
                        <input id="my_theme_options[primarycolor]" class="regular-text" type="text" name="my_theme_options[primarycolor]" value="<?php esc_attr_e($options['primarycolor']); ?>" />
                    </td>
                </tr>

                <tr valign="top">
                    <th scope="row">Upload Header Logo</th>
                    <td>
                        <input id="my_theme_options[headerurl]" type="text" size="36" name="my_theme_options[headerurl]" value="<?php esc_attr_e($options['headerurl']); ?>" />
                    </td>
                </tr>
            </table>
            <p class="submit">
                <input type="submit" class="button-primary" value="<?php _e('Save Options', 'a1theme'); ?>" />
            </p>
        </form>

<?php settings_fields('my_options'); ?>

<?php $options = get_option('my_theme_options'); ?>

<td>

</td>

</tr>

<th scope="row">Upload Header Logo</th>

<td>

</td>

</tr>

</table>

</p>

</form>

Open the form with the action ‘options.php’ this ensures that all options are submitted to the wp-admin file ‘options.php’ – no further action required by us. That pre-existing file handles it all.

All classes and formatting, I tried to emulate from WordPress’ own forms, just to keep it all consistent and familiar.

The main lines of note are the options setting fields (below).
They allow the form to connect to the database of options.

<?php settings_fields('my_options'); ?>
<?php $options = get_option('my_theme_options'); ?>

1 2	<?php settings_fields('my_options'); ?> <?php $options = get_option('my_theme_options'); ?>

After adding the form, you should successfully be able to access the Theme Options page, and view/edit/update the options you’ve defined (ensure you’ve added the sanitisation function at the bottom of the page to clean the output for database submission).

Doing Something with our Theme Options

In my header.php file, I would like to add my header image and define some additional styles, to include the primary colour option.

The first line I add at the top, tells the file to read the options we set up earlier. From this point we can access the variables directly.

$options = get_option('my_theme_options');

1	$options = get_option('my_theme_options');

Now, I can add some CSS styles to take advantage of the output.
Underneath the wp_head(); declaration, I can add a style tag:

<style>
#branding{
    background:url('<?php echo $options['headerurl']; ?>');
}
h1, h2, h3 {
    color: <?php echo $options['primarycolor']; ?>;
}
</style>

<style>

#branding{

background:url('<?php echo $options['headerurl']; ?>');

}

h1, h2, h3 {

color: <?php echo $options['primarycolor']; ?>;

}

</style>

I inject PHP directly into the HTML/CSS Style declaration. Now the primarycolor variable, we set earlier, affects the header tags and the branding div on our page has a background image of the headerurl variable.

Sanitisation Function

function theme_options_validate($input) {

    // Say our text option must be safe text with no HTML tags
    $input['primarycolor'] = wp_filter_nohtml_kses($input['primarycolor']);
    $input['headerurl'] = wp_filter_nohtml_kses($input['headerurl']);

    return $input;
}

function theme_options_validate($input) {

// Say our text option must be safe text with no HTML tags

$input['primarycolor'] = wp_filter_nohtml_kses($input['primarycolor']);

$input['headerurl'] = wp_filter_nohtml_kses($input['headerurl']);

return $input;

}

Now, the user can use Theme Options to define a primary colour for the headers and add a url for an image to their header.

Hopefully, now you know the basics, you’ll be able to experiment and build upon it!

Comments

comments