A Sample WordPress Theme Options Page
Problem: You want to create a simple theme options page for your new WordPress theme but all the tutorials and sample theme options pages you’ve seen are way too complex or don’t fit in at all with the existing WordPress look.
Solution: We’ve come up with a simple, sample theme options page you can use for your next theme!
We’ve based this theme options page on the awesome sample plugin options page created by Ozh of Planet Ozh—only now with the bonus Radio and Select options and a Text Area.
Everything is bundled up in a Twenty Ten child theme called A Theme Options Theme—an instant working example—that you can download at the end of this post but here’s how you’d want to use it in your own themes …
How To Use theme-options.php
First, drop theme-options.php in your theme directory and include it in your theme functions.php file like so:
require_once ( get_template_directory() . '/theme-options.php' );
Or, if you’re including the options page with a Child Theme (just like in A Theme Options Theme) like so:
require_once ( get_stylesheet_directory() . '/theme-options.php' );
Then, whenever you need access to one of your new settings, you can do something like the following in any theme template …
<?php
$options = get_option('sample_theme_options');
echo $options['sometext'];
?>
Pretty simple, right? While you’re at it, you’ll probably want to use your text editor’s find and replace feature to change “sample” in theme_options.php to the name of your theme. So, for example, if your theme was named Shabadoo you’d go from this …
register_setting( 'theme_options_options', 'theme_options_sample', 'theme_options_validate' );
to something like …
register_setting( 'shabadoo_options', 'shabadoo_theme_options', 'theme_options_validate' );
Of course, Shabadoo is only a suggested theme name. But if you’d like to use it, it’s all yours. Just like theme-options.php is all yours. We hope you can use it to get a quick start on enhancing your themes with a simple options page. Good luck.
Download A Theme Options Theme.
47 thoughts on “A Sample WordPress Theme Options Page”
Genius! Thank you so much for this. Much better than my few boring text boxes and buttons in a table.
Great. Seems very easy to implement and just what i needed for a next project. Thanks!
Ian, brilliant as always, Sir.
I can’t help but feel that the only thing ‘missing’ from this excellent little resource is an example about how to deal with file uploads. Plenty of themes allow the end user to upload a logo or other media and I know you can ask the user to upload it into the media library and then copy and paste the url of the file into a text input (as many, many themes do) but having a theme guru such as yourself show us how to ‘properly’ handle file uploads can only be a positive thing for the community.
I know file uploads are normally a bit of a ‘touchy subject’ but WP has the functions to handle them (and after countless hours googling I did find a solution which I think works well) but I’d love to see something of an ‘official’ way to deal with this.
On an unrelated note, I’ve seen a few themes (and plugins) that use 2 columns and utilise meta-boxes to hold the different option groups which really makes them look native and after all, familiarity is key!
Thoughts?
To answer both questions, I prefer simpler theme options. For logo uploading, WordPress already has the Custom Header feature cooked in. And, when it comes to 2-column theme options with metaboxes I like to point to WordPress’ own settings pages. They don’t need multiple metaboxes or multiple columns—and if a theme has more options than WordPress … it has too many options.
Hmm – Would be interesting to see this evolve into a Widgetized theme options (Is that even possible?) — allowing widgets to be added to the options panel. Perhaps offloading some developer work to existing plugins that come in the form of widgets.
I think one of the Google Summer of Code projects for this year has to do with making a more generalized admin widgets framework. Perhaps something will come out of that like what you’re thinking of.
Thank you sir
Pingback: links for 2010-06-04 | Links | WereWP
Really nice work sir. This should be helpful for future projects where someone is going to want this.
Pingback: Round Up For the Week Ending 04-06-2010
This is what I was looking for those last days!
I’ve seen some tutorials about creating an option page for theme, and even looked through the Thematic code and found that all of them use the same techniques. But this code is a bit improved with just one option, that’s quite good. I’ll check it right now. Thanks for sharing.
Pingback: links for 2010-06-05 :: zota
I added the theme options file and included it in functions.php, but the theme options page does not appear in the admin.
how can I fix this?
Hi, Paul. Did you use the example above, with
require_once()?will this code only work with WP 3.0?
yes, I added it as the first line of functions.php
where should the menu appear? under Appearance?
how can I debug this?
thanks!
ok, I just installed WP 3.0 RC and it’s working.
Pingback: Weekend Roundup #86
sorry about all these comments but I have another problem: the value for the dropdown returns to the default value when I click save.
how can I preserve the selected value?
Hi Paul, email me the code and I’ll take a look at it.
Fantastic! Now I need to see what wicked ideas we all can implement!
a customization guide would be nice.
I iddn’t manage to get the select to work with categories
To make the select box with WP categories, I just changed the code to:
$cats = get_categories();
foreach($cats as $cat){
$select_options[$cat->term_id]["value"] = $cat->term_id;
$select_options[$cat->term_id]["label"] = $cat->name;
}
Excellent. Thanks for the update, Paul.
except it doesn’t work
but I posted the question on wpquestions.com – hopefully I’ll be able to get this sorted
I used some (similar) code from the Acamas child theme options page which seem to work:
$cats = get_categories(‘hide_empty=0′);
foreach($cats as $cat){
$select_options[$cat->cat_ID]["value"] = $cat->cat_ID;
$select_options[$cat->cat_ID]["label"] = $cat->cat_name;
}
Also needed to remove the original array defined in $select_options, otherwise the other values remained in the drop-down.
BUT, it doesn’t work if I try to define a custom select box, eg $featured_options. I can get the list of categories but can’t save the option.
Any ideas? I can’t figure it out as my PHP knowledge is limited to cut-and-paste.
this seemed to work for me , change this:
// Our select option must actually be in our array of select options
if ( ! array_key_exists( $input['selectinput'], $select_options ) )
$input['selectinput'] = null;
to this:
$input['selectinput'] = $input['selectinput'];
now you should be able to save
Thank you so much! I’ve been trying to dive into theme options for the custom themes I build for clients. I’ll give this one a try on my next project.
Hi there,
thanks for this hack. I spent whole day with modifying this code but I have no luck to add a reset button. Is possible to add a reset function (delete_option or something like that) to get default values? I am confused. Thanks for help.
That sounds like something that might make a good future update to the sample options.
some default values would be nice as well
I have found a solution for the reset function however it’s not the best one. But good for start. Under this line
if ( ! isset( $_REQUEST['updated'] ) ) {$_REQUEST['updated'] = false;
Put this:
if( isset( $_REQUEST['reset'] )) {
global $wpdb;
$query = "DELETE FROM $wpdb->options WHERE option_name LIKE 'option_name'";
$wpdb->query($query);
header("Location: themes.php?page=theme_options");
die;
}
Don't forget to modify the option_name to your own option name value.
And another modification is to add Reset button.
Under this line
<input type="submit" class="button-primary" value="" />