Posted on 12:51, May 31st, 2008 by 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.
[singlepic=27,210,200,,right]
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:
- How to create regular WordPress theme
- 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:
[singlepic=26,300,240,,center]
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.
[Download id not defined]
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.
Tags: 
Posted in
[...] [...]
Great article. I have a question, how would you use the options within a stylesheet, lets say if I name the style.css to style.php?
Main stylesheet used by the theme MUST be named style.css (WordPress requires that). But you can create another file and name it ’style_xtra.css.php’. There is an easy way to load options from WordPress and you can see that piece of code in Starscape source (latest version): folder ‘themes\classic\’ file ’screen.css.php’. I was planning to cover this in my next tutorial next week.
[...] Theme: Creating setting page for wordpress theme Tutorial de 6 pasos para crear tu propia clase que te crea tu pagina de [...]
Usefool post, thx
Great post, thanks a lot!
Useful post. good luck.
i love igoogle
igoogle is a place that is where we serch for things.
Wow, interesting info, i need to try this. bookmarked.
@ MillaN and Dipankar
No, it is not necessary that the stylesheet is named with a .css extension. You can use style.php in the link tag (head) but you must put a content type declaration inside the file style.php.
[CODE]
[/CODE]
Just place that on top of the style.php file and you can use it as a css file.
Oops.. code didn’t show..
@ Darren Pangan
By default WordPress requires existance of ‘style.css’ file, there is no way to change that without changing WordPress. Also, official WordPress theme website requires this file. So, all the custom css generated with php must go in some other file.
And, Firefox 3 has a problem with CSS files that don’t have CSS extension. Important is the file header generated by PHP, but for some reason Firefox3 requires valid extensiosn for CSS.
@MillaN
It’s true that WordPress requires the style.css file so the dynamic css file (if named with a .php extension) should go to another file.
I don’t know about Firefox 3 having problems with CSS files not having “.css” extensions. I’m using Firefox 3 and my themes that I created with dynamic CSS having .php extension works no problem.
yea im using mozilla too and i have had any problems
Nice work – can’t wait to test it out. You might want to proofread your post once through though…
Great tutorial, dude. It worked like a charm. Thanks for all your help.
Does it work on wordpress 2.7?
Yes, it works in WP 2.7.
Nice… Clean code too. I like how you use a class for this. Will sure help me organize my codes. Thanks for the tutorial.
I want to build a background color customization to my theme, how can I build it?
thaks in adavnce
Can you be more specific?
Great coding, but on the setting page I created, none of the data that was previous saved shows up. I have the correct code in the value of the fields and such, but it doesn’t show and I have to re-enter all the fields again if I want to edit one thing. It shows up fine on where I put it in wordpress, just not in the custom page. Any help? Thanks in advanced.
Great article, I am going to try this.
Thanks a lot!
Hi,
Great Tutorial!
I’d be interested in being able to add a Control Panel to a theme that would allow for…
1.0 changing the default background or color values
2.0 allowing an admin to upload header pic (and other relevant pics such as navbar backgrounds)
I’ve tried to look at Kubrick on the default theme to now avail…
Anyone have a pointer I can review?
Excellent article once again. Keep up the good work!
[...] Create settings page for WordPress theme [...]
great post! keep up the good work
[...] Cats Who Code has a nice tutorial that shows how theme designers can create a simple options panel that allows users to make some modifications to the theme. Control panels can make themes more user-friendly and reduce the need to edit theme code. Starscape also has a tutorial for creating a settings page. [...]
[...] Cats Who Code has a nice tutorial that shows how theme designers can create a simple options panel that allows users to make some modifications to the theme. Control panels can make themes more user-friendly and reduce the need to edit theme code. Starscape also has a tutorial for creating a settings page. [...]
[...] Create settings page for WordPress theme [...]
[...] Cats Who Code has a nice tutorial that shows how theme designers can create a simple options panel that allows users to make some modifications to the theme. Control panels can make themes more user-friendly and reduce the need to edit theme code. Starscape also has a tutorial for creating a settings page. [...]
[...] I based my code on this example: http://blog.starscapetheme.com/2008/05/31/create-settings-page-for-theme/ [...]
[...] 4. Create A Settings Page for WordPress Theme [...]
[...] 20. Create settings page for WordPress theme [...]
This entry was a good read! I could not have stated things better myself.
thanks for posts
[...] 4. Create A Settings Page for WordPress Theme [...]
This entry was a good read! I could not have stated things better myself.
[...] 10. Create settings page for WordPress theme [...]
Hi, I have a problem, as the following:
if (!is_array(get_option(‘themename’)))
add_option(‘themename’, $this->default_settings);
$this->options = get_option(‘themename’);
You receive the error:
Parse error: syntax error, unexpected T_IF, expecting T_FUNCTION in D:…\themes\planmysite\panel\controlpanel.php on line 40
Why?
PS. You can request access to download source code?
[...] Create A Settings Page for WordPress Theme [...]
I created a new wordpress site and I don’t have a good design yet. But I hope your tutorial will help me a bit, but it looks complicated for a beginner like me.
Themes…
I saw this really good post today….
I just started playing under the hood of wordpress to customise a theme, and i found this tutorial useful to understanding how wordpress works.