Not many Wordpress themes have additional settings page where blog admins can adjust some of the themes settings. One of the reasons for this is hard to find examples describing in details what you need to do, although documentation has some basic info about that. Also, most themes don’t need such settings page, or is too hard to implement theme design that could be flexible to change like this.

Most themes can be customized by editing php and css files, but this can be a problem for most users, who use blog as tool, and don’t know much about web design. For them it would be much more convenient to have simple page in their admin panel and selection of options to tweak.

This article will show you step by step how to create options page for your theme, how to save settings and how to use them in your theme. Mine Starscape theme will be used as a reference in some points, so you might also want to download it and check for yourself what can you do with settings page.

Just to be clear, I am not going to create nothing fancy here, I will keep the code simple, so you can see what’s going on. If you want more details you can always take a look at Starscape theme code.

Requirements:

For this to work, you need to know:

1. How to create regular Wordpress theme
2. How to work with PHP classes

Step 1: Required Files

For what we are going to do, we need file ‘functions.php’ that should be located in your theme folder. If it’s not there, then you will need to create it. Functions file will be included in Wordpress execution cycle.

Also, you will need one more file where you are going to add code for your settings page. Example I will create here, will use class approach because it will be much easier to maintain in the future. Let’s call this file ‘controlpanel.php’. It would be good to create separate folder for all files related to control panel. Create such folder and call it ‘code’. Also, in this folder add one css file called ‘controlpanel.css’ where you are going to put all css styles you are going to use on your control panel page.

So, the files we need:

functions.php
code/controlpanel.php
code/controlpanel.css

Step 2: Basic Control Panel class

In ‘controlpanel.php’, add following code:

1
2
3
4

class ControlPanel {
  function ControlPanel() {
  }
}

And now add code to the ‘functions.php’ file for loading control panel:

1
2

require_once(TEMPLATEPATH . '/code/controlpanel.php');
$cpanel = new ControlPanel();

This is the only thing you need in this file. This will load control panel class, and create an instance of it. Constructor for this class will actually do all the work. Functions file usually contains functions needed for a theme to work (sidebars rendering). You can either leave that in the ‘functions.php’, or you can move them to the class we created. This way this class can store all needed functions for the theme, and handling of the theme will be easier.

Step 3: Adding Wordpress actions

Next we need to to, is to make Wordpress aware of our settings page. For this, we need to add some Wordpress actions into class constructor, and methods for this actions. So, now your ‘controlpanel.php’ should look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

class ControlPanel {
  function ControlPanel() {
    add_action('admin_menu', array(&$this, 'admin_menu'));
    add_action('admin_head', array(&$this, 'admin_head'));
 
    if (function_exists('register_sidebar'))
        register_sidebar(array('name' => 'Sidebar'));
  }
 
  function admin_menu() {
    add_theme_page('Theme Control Panel', 'ThemeCP', 'edit_themes', "themename", array(&$this, 'optionsmenu'));
  }
 
  function admin_head() {
    echo '<link rel="stylesheet" href="'.get_bloginfo('template_url').'/code/controlpanel.css" type="text/css" media="screen" />';
  }
 
  function optionsmenu() {
  }
}

In line 4 we are adding action ‘admin_menu’. This will add execution of the specified function into wordpress for administration menu rendering. And in line 5, action ‘admin_head’. This will add execution of the specified function into wordpress for administration page header.

As you can see, function is specified as an array, because we are using class. Array has two elements, one is specifying instance of the class with &$this and the other is name of the function in class to call.

Admin head action renders head part of the page, and we are going to add css file here as you can see in line 13. Here, we are using wordpress function ‘get_bloginfo’ to get full url to template folder.

Admin menu is the wordpress action used for rendering complete wordpress menu, and in line 9 we are adding new subpage in the design page using function ‘add_theme_page’. First parameter is not very important, and it’s name of your page. Second one is actual title of your options page. Third paramenter should remain always ‘edit_thames’. Forth parameter should be name of your theme. And in the line xx we are registering one sidebar. And once again, array specifing function to call when user want to access this new page. After you add all this, your design menu should look like on the picture:

Step 4: Theme Settings

The best way to store settings related to the theme is to use Wordpress build-in options mechanism that uses options table in the database. You can add one or more separate options. One options record can be used to store many different settings in array or class. We will use array approach here.

I like to have one array in the class with default values for all settings. For this example we will have two settings, so we can keep things simple:

• display_blog_title
• blog_title_color

So, add this in the ‘ControlPanel’ class definition:

1
2
3
4

var $default_settings = Array(
  'display_blog_title' => 1,
  'blog_title_color' => '#FFFFFF'
);

And also, add this in class constructor:

1
2
3

if (!is_array(get_option('themename')))
  add_option('themename', $this->default_settings);
$this->options = get_option('themename');

And again, ‘themename’ you can change with the name of your theme, or something else, but be careful to use unique name and be sure that no other theme or plugin, or wordpress uses that name for thier settings. This will add new option in the database. Last line will load settings into class variable ‘$options’.

Step 5: Actual Settings Page

Well, after all this, now is the time to actually show user controls for the settings we want. All code that has to handle this will go in ‘optionsmenu()’ function. Settings page is (almost) only rendering html for FORM and form elements. In our case we need one checkbox and one input field. Code that follows is very self explanatory, so I will not go in too many details about it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

function optionsmenu() {
  if ($_POST['ss_action'] == 'save') {
    $this->options["display_blog_title"] = isset($_POST['cp_displayblogtitle']) ? 1 : 0;
    $this->options["blog_title_color"] = $_POST['cp_blogtitlecolor'];
    update_option('themename', $this->options);
    echo '<div class="updated fade" id="message" style="background-color: rgb(255, 251, 204); width: 300px; margin-left: 20px"><p>Settings <strong>saved</strong>.</p></div>';
  }
 
  echo '<form action="" method="post" class="themeform">';
  echo '<input type="hidden" id="ss_action" name="ss_action" value="save">';
  echo '<input type="checkbox" name="cp_displayblogtitle" id="cp_displayblogtitle"'.($this->options["display_blog_title"] == 1 ? ' checked' : '').' /><label style="margin-left: 5px;" for="cp_displayblogtitle">Display Blog Title</label><br />';
  echo 'Blog Title Color: <input class="widefat" style="text-align: right; width: 65px" name="cp_blogtitlecolor" id="cp_blogtitlecolor" type="text" value="'.$this->options["blog_title_color"].'" />';
  echo '<p class="submit"><input type="submit" value="Save Changes" name="cp_save"/></p>';
  echo '</form>';
}

So, praticlly there are two parts, first will be used to save data posted by the form, and the other parts is actual form will all the settings we need. Also, notice that we have used CSS class for FORM tag. This class is in ‘controlpanel.css’ file.

Step 6: Change Header

No that we have working settings page is time to put these settings to work. For this two settings to work, we need to modify ‘header.php’. We need to load settings from database, and then simple use each setting to modify the rendering.

1
2
3
4
5
6

$theme_options = get_option('themename');
if ($theme_options["display_blog_title"] == 1) {
  echo '<div id="header_title" style="color: '.$theme_options["blog_title_color"].'">';
  bloginfo('name');
  echo '</div>';
}

This is only the piece of the code that shows blog title and sets the color depending on our settings.

Download source code

I have compiled the files we have created and changed in this article, so you can download them. Header file is more or less typical header file, you can easily add the code we created above to any existing header file with similar structure.

Conclusion

Well, I hope you liked this post, and that you will find it useful in creating your own custom settings pages for themes. If you have some additional questions use this comments page, forum or contact form.