Options Framework Plugin

The Options Framework Plugin makes it easy to include a full featured options panel in any WordPress theme.

I built this plugin so theme developers can concentrate on making the actual theme rather than spending a ton of time on building an options panel from scratch. It’s free to use in both commercial and personal projects, just like WordPress itself.

There’s also a theme version if that better fits your project.

Video Demo

Options Framework Plugin from Devin Price on Vimeo.

When Not to Use This Plugin

If you just have a couple options and none of them are complicated color pickers or image uploaders, I’d recommend checking out “A Sample Theme Options Page” from Ian Stewart. Using the Options Framework in this case would be overkill.

Instructions

Download the plugin and activate it on your site.

To learn how to set up the options panel in your own themes, download the Options Check theme from GitHub (a child theme of Twenty Eleven) and use its files as a base. It’s a blueprint for how the Options Framework works with a sample option panel with every type of option you are able to use and a demo of how to display each one on the front end. To get started:

1) Copy “options.php” from the Options Check theme into your own theme.
2) Edit the array in “options.php” to define the options you want to use.
3) Add the following function to your theme so it will use default settings even if the Options Framework plugin is not installed:

/*
 * Helper function to return the theme option value. If no value has been saved, it returns $default.
 * Needed because options are saved as serialized strings.
 *
 * This code allows the theme to work without errors if the Options Framework plugin has been disabled.
 */
if ( !function_exists( 'of_get_option' ) ) {
function of_get_option($name, $default = false) {
	$optionsframework_settings = get_option('optionsframework');
	// Gets the unique option id
	$option_name = $optionsframework_settings['id'];
	if ( get_option($option_name) ) {
		$options = get_option($option_name);
	}
	if ( isset($options[$name]) ) {
		return $options[$name];
	} else {
		return $default;
	}
}
}

Available Options

These are the options currently available. If you feel there is something I left out, get in touch and perhaps I can add it.

  • text
  • textarea
  • checkbox
  • select
  • radio
  • upload (an image uploader)
  • images (use images instead of radio buttons)
  • background (a set of options to define a background)
  • multicheck
  • color (a jquery color picker)
  • typography (a set of options to define typography)

There’s also “heading” to define the menu tabs, and “info” if you just want to add some additional information to the panel.

Returning Option Settings

If you look in index.php of the Options Check theme, you’ll see how each option is returned. It should look something like this:

of_get_option($id,$default);

What if the Options Framework Plugin is not installed?

The neat thing about this plugin is that it isn’t required for you theme to work. Each option should have a default which will be used if the plugin isn’t installed. Take a look at Portfolio Press without the plugin activated to see how it works.

There are a couple ways to let the user know that options are available if the plugin is installed: a notice on theme activation, an auto prompt on activation, notes in the documentation, etc. I’ve left this up to the theme authors to decide how to implement.

In Portfolio Press I created a theme options page with a message, which will get overridden if the actual plugin is installed. The code looks like this (which you’re welcome to use):

if ( !function_exists( 'optionsframework_add_page' ) && current_user_can('edit_theme_options') ) {
	function portfolio_options_default() {
		add_submenu_page('themes.php', 'Theme Options', 'Theme Options', 'edit_theme_options', 'options-framework','optionsframework_page_notice');
	}
	add_action('admin_menu', 'portfolio_options_default');
}
/**
 * Displays a notice on the theme options page if the Options Framework plugin is not installed
 */
if ( !function_exists( 'optionsframework_page_notice' ) ) {
	function optionsframework_page_notice() { ?>
		<div class="wrap">
		<?php screen_icon( 'themes' ); ?>
		<h2><?php _e('Theme Options'); ?></h2>
        <p><b>If you would like to use the Portfolio Press theme options, please install the <a href="https://github.com/devinsays/options-framework-plugin">Options Framework</a> plugin.</b></p>
        <p>Once the plugin is activated you will have option to:</p>
        <ul class="ul-disc">
        <li>Upload a logo image</li>
        <li>Change the sidebar position</li>
        <li>Change the menu position</li>
        <li>Display the portfolio on the home page</li>
        <li>Hide the portfolio image on the single post</li>
        <li>Update the footer text</li>
        </ul>
        <p>If you don't need these options, the plugin is not required and the theme will use default settings.</p>
		</div>
	<?php
	}
}

Download the Plugin

Download from WordPress Repository
Download Development Version

Future Development

If you’re looking to do something with the plugin that isn’t currently possible, post it in the comments.

Exporting/Importing Options

If you are exporting SQL databases, this thread might be of interest to you. There’s also a fork of the theme version, where someone built this out: https://github.com/vauvarin/options-framework-theme

Credits

The Options Panel was originally based on the excellent work of Woo Themes and still uses some of their code.

A huge thanks to all the people who helped out in GitHub while this project was in development, especially @mfields, @helgatheviking, @celtic7, @samargulies and @Mamaduka.

Also a big thanks to folks who made donations to pay for a third party code review: Jason Schuller, Mint Idea, Luke McDonald and Bas Debie.

If you would like to donate to the ongoing plugin development, hook me up with a PayPal donation.

231 comments on “Options Framework Plugin”

  1. Love the plugin! Please keep up the good work.

    Is there a way for a check box to print or echo html to the homepage source?

    Example: If the checkbox was checked it could display a button or a link. If the checkbox wasn’t checked, it wouldn’t show the button or link on the homepage.

    Let me know how I can donate to this project too.

    Thanks!!!

    Reply ↓

  2. So far this theme control panel setup is awesome, but I do have a couple questions…first is with the plugin (which I can see the advantages), is there a way to change the path of the options.php file from the theme root to a sub-directory in my theme? And second, is there a way to customize the css for the control panel?

    Reply ↓

    • The plugin looks for options.php in the root directory of the active theme or child theme. You can’t change that without hacking the plugin.

      You can add in your own stylesheets though. There’s an action optionsframework_custom_scripts hook you can add css to. I haven’t experimented too much with this though, so if you need a better hook just let me know. I’ll also play with it some more when I get a chance.

      Reply ↓

      • Hi Devin…thanks for the follow up. I actually got the other version (not the plugin one) and integrated it into my theme I am making. So far I have to say this control panel of yours kicks butt! I was also able to change where the script looks for the options.php (which I moved into a folder called themeSettings). I’m going to play with this for a while and see how things go, but again, I really like this one. By the way, unless I missed it somewhere, is there an options setting if one uploads an image for a page background, a setting to control how it repeats (tiles)?

  3. Hey Devin, Great plugin! Just a quick question, I was testing it on the Options Check theme and it seens that the Typography settings are only changing the font’s color and size, while the font face and style continues unchanged on the example. On the list of settings used on Typography under the example, it lists the right the font and style I chose on the options page, but not on the example. Any ideas on how to fix it? Thanks

    Reply ↓

  4. Hi,

    Thanks for the goodness.
    I want to enable the option page for editors, not just administrators. I changed option-framework.php and replaced add_submenu_page to add_menu_page. I also changed the ‘cabalitiy’ from edit_theme_options to edit_published_pages according to WordPress Codex however the option menu only shows when users are logged in as administrator. I tried many only editor and up capability but no luck so far.
    Is there anything I should change to make this work?

    Thank you.

    Reply ↓

    • Ok. If you want to enable options framework’s panel for editor or other user roles other then administrator do the following:
      Change option-framework.php on line 41: change capability to something like moderate_comments (both admins and editors are able to do so), then go to line 182 and change add_submenu_page to add_menu_page according to WP codex.
      It’s an important step if you don’t want to grant access the whole menu with its submenus, like editor… Don’t forget to replace edit_themes_options to moderate_comments (or any other capability) and save the file.

      Unfortunately this is not enough – the options admin menu shows up for editors but they are unable to save its settings.
      Open wp-admin/options.php and change the capability at line 27 to the same you used in options-framework.php.

      Editing WordPress core files are not advised, but in this case it looked as the only option. Make a note, not to forget your change when updating WP and the plugin.

      You can make more secure the above procedure if you register a new capability, and use that at both php file mentioned above.

      Thanks for the plugin.

      Reply ↓

  5. I need help with the typography output. I’ve added more web safe fonts to the array but I can’t get it to output correctly. I need the fonts to look like this:
    {font: 12px normal ‘Lucida Sans Unicode’, ‘Lucida Grande’, sans-serif;}

    but they output like this:
    {font: 12px normal lucida;}

    The lowercase, single word, sanitized version outputs but it isn’t recognized by CSS.
    I’m using ‘ . $typography['face'] . ‘ in the inline css.

    Any help would be appreciated.

    Reply ↓

      • Yes, that’s what I did but the output doesn’t give the correct format for CSS typography. Fonts with multiple words need to be wrapped in single quotes and I would also like it to output the whole font family.

      • I’ll make a note to test that more. But in the meantime you can just output the css as individual rules right? font-family, font-size, etc.

  7. Hi Devin
    I like the look of this-I just need to explore it more..
    The reason I was looking for a theme options panel was to add the ability to change bg nav color on 2010/2011 access menu. Grateful if you would consider adding this option.
    Thanks & best wishes

    Reply ↓

    • The plugin just provides a framework for building options. It doesn’t provide specific options for specific themes unless a developer builds them in.

      Reply ↓

  8. Pingback: Adding Theme Options To WordPress Child Themes

  9. Hi,
    Thanks a lot for your work.
    There is just a little bug for websites with accents (à é ê…). When I try to make an heading with a word with an accent, it doesn’t work. It shows the options the first time, and if you go to the other tab and come back, nothing is in the table.
    Do you think that their is a solution ?

    Reply ↓

  10. Hi! Awesome plugin! But I encounter some problem when using the “upload” function. I tried to use an image but instead the upload popup windows just hang in there without doing nothing. Hopefully anyone could help me. Thanks :)

    Reply ↓

  11. Hi,

    Wonderful plugin Devin! Saves me alot of time.
    I’m having some issues with saving the options from the admin panel. The interesting thing was it used to work, but now it just show the default value and refuse to save any updates. I’m using the text box, image uploader, text area, and page selector. None of them saves anymore.

    Anyone can help? Thanks!

    Reply ↓

  13. Is there a way to use this framework for a plugin options panel rather than a theme options panel? I love the look and feel of the options panel and would like to use it for my plugin options.

    Reply ↓

  15. thanks for the plugin, but i am not sure i have done it right. the options are appearing in chinese??

    can you tell me how to convert in into english. its dispatch theme for wordpress

    thanks

    Reply ↓

  16. Great work Devin. Quick question though – why do select boxes save a numerical value? I am having to map these values back to usable options and it seems really clunky.

    For example, with this select box:
    blindXblindYblindZ...

    I need the option text but can’t get it through of_get_option. So I am running a huge switch statement to convert the values back to the option text which is pretty horrible duplication.

    Am I missing something or is there a better way to handle this?

    cheers
    Anthony

    Reply ↓

    • You should be passing it an array, which has a key and a value for each item you want to show up in the select option. The key is what gets saved into the database, so one solution is to have your key match your value. Another is to just make that array a global, and then you can access it from any theme file.

      Reply ↓

  17. Thanks for this (plugin version and theme version), I’ve been looking for something like this for quite some time.

    It works great, my customers are happy to be able to change their settings – and I don’t have to program everything from scratch again and again ;-)

    Thanks!

    Claudia

    Reply ↓

  18. AWESOME PLUGIN!

    I’m trying to make a custom css text area and am unsure of how to retrieve it from my options.php. I think it would go in my header.php but what code?
    Any help would be much appreciated.

    Reply ↓

  19. Hi there,

    It seems that the framework can’t save javascript use textarea.

    The script broken when saving.

    I want to save the script:

    jQuery(window).load(function() {
    jQuery('#slider').nivoSlider({
    animSpeed:1000,
    beforeChange: function(){},
    afterChange: function(){},
    slideshowEnd: function(){} //Triggers after all slides have been shown
    });
    });

    However, after the code saved, it will break. Your Portfolio Press also can’t save these data.

    jQuery(window).load(function() {
    jQuery('#slider').nivoSlider({
    animSpeed:1000,
    pauseTime:3800,
    afterChange: function(){},
    slideshowEnd: function(){} //Triggers after all slides have been shown
    });
    });

    Reply ↓

  20. ??
    Can’t post code??

    Hi there,

    It seems that the framework can’t save javascript use textarea.

    The script broken when saving.

    I want to save the script:
    <code>
    <script type=”text/javascript”>
    jQuery(window).load(function() {
    jQuery(‘#slider’).nivoSlider({
    animSpeed:1000,
    beforeChange: function(){},
    afterChange: function(){},
    slideshowEnd: function(){} //Triggers after all slides have been shown
    });
    });
    </script></code>

    However, after the code saved, it will break. Your Portfolio Press also can’t save these data.

    <code>

    jQuery(window).load(function() {
    jQuery(‘#slider’).nivoSlider({
    animSpeed:1000,
    pauseTime:3800,
    afterChange: function(){},
    slideshowEnd: function(){} //Triggers after all slides have been shown
    });
    });

    </code>

    Reply ↓

  21. Great plugin, it’s working out very nicely for us so far.

    When you use the Image Selector, is there a way to present large images without busting apart your admin layout? For example, I’m posting a handful of header images for the user to choose from and they’re about 800 pixels wide. Is there a way to automatically scale those images down in the admin area for ONLY that array?

    Thanks.

    Reply ↓

      • Thanks for the quick reply. Two questions.

        1) How do I include thumbnails in the THEME OPTIONS section of Admin? I’ve included the array below. Currently it’s displaying the entire image.
        2) How do I output the full PATH using the array below? For example… of_get_option(‘headerimage_options’); will just return “Cityscape” rather than /full/path/here/cityscape.jpg. Thanks for your help.

        ——————————–

        $options[] = array( “name” => “Header Image”,
        “desc” => “Available header images for this wireframe layout.”,
        “id” => “headerimage_options”,
        “std” => “default”,
        “type” => “images”,
        “options” => array(
        ‘Cityscape’ => $headerimagepath . ‘cityscape.jpg’,
        ‘Clouds’ => $headerimagepath . ‘clouds.jpg’,
        ‘Flowers’ => $headerimagepath . ‘flowers_red.jpg’,
        ‘Forest’ => $headerimagepath . ‘forest.jpg’)
        );

      • Well, first off, for header images you should be using the built-in WordPress functionality: http://codex.wordpress.org/Function_Reference/add_custom_image_header. If you’re worried users will miss it, you can put an “info” item in the options panel that links them over to it.

        But, to answer your question, the path you provide for the options panel should be the smaller resized image ‘cityscape-thumbnail.jpg’, for example. When you output the the image in the theme, you’ll have to do conditional statements, if option == cityscape { echo larger city scape image }, for example. The image radio buttons weren’t built to to display or hold the actual image value- I can only think of a few specific use cases where that would even make sense.

  22. Devin what is the best route for moving sites and dealing with the theme options. Usually I have to manually update all the theme options because doing db replacement destroys them. Interested in your thoughts on the matter.

    Reply ↓

  23. Pingback: Building WordPress Themes You Can Sell

  25. Devin,

    I’m well on my way to creating my own Options page thanks to you. My question now is regarding the use of the checkbox to make hidden fields visible in the Options Interface. Each time I change either of the id’s that you give in the OF Plugin for inputs with a “hidden” class (example_text_hidden & example_showhidden), the checkbox does not work. Meaning, no new fields are revealed once it’s checked. If I change these ids, and I certainly want to, do I have to add them in somewhere else to get this functionality working again?

    Thanks and take care,
    AC

    Reply ↓

  26. Great stuff. Was wondering if it’s possible to have this work independently of the “theme options” so that it can be placed as it’s own page/item on the dashboard menu. I’m trying to basically use this for getting additional information of users.

    Reply ↓

  27. I want to use this framework within my own theme, do I just import the options.php file in to my theme folder? Then which function do I use to display the theme options page? I can get it to display the message about installing the plug in, but want to be able to use this framework without having to ask the user to install anything else.

    Reply ↓

  28. Hi Devin,

    Great plugin as I’ve used it before in other projects but now I’m stumped.

    I’m currently using a child theme for the Yoko theme, and I was trying to test out Noel Tock’s Themeforce Framework. But after adding the options code I’m still getting the error saying my theme doesnt support the plugin.

    I really can’t figure out why unless I didn’t copy all the code in from the options.php and this site properly.

    I’m not running multisite or anything like that. Any thoughts on why I’m getting this error?

    Reply ↓

  29. Hi Devin, great plugin but i have very complex problem (for me)

    when i click save option no thing saved, i change wp_debug to true and have the following error
    Cannot modify header information - headers already sent by (output started at C:\AppServ\www\mytheme\admin\options-framework.php:335) in C:\AppServ\www\byt\wp-includes\pluggable.php on line 934

    line 335
    // For a value to be submitted to database it must pass through a sanitization filter
    if ( has_filter( 'of_sanitize_' . $option['type'] ) ) {
    $clean[$id] = apply_filters( 'of_sanitize_' . $option['type'], $input[$id], $option );
    }
    but i work with the same plugin before and work great, i have no idea why stop working now

    Reply ↓

  30. Does the plugin work with multisite? Anything I would need to do differently?

    Just looked at the tutorial on this and love the way you’ve set it up – perfect for developers. If I can use it for multisite will save me a ton of time.

    Reply ↓

  31. I just did a fresh wordpress install, installed the Press75 ‘On Demand’ theme, then installed the Options Framework from within the theme. Haven’t done any customizing of the theme yet. Went to try to save some settings in Theme Options, and I’m getting an internal server error. I pasted the error at the bottom of this comment.
    I have the latest version of WordPress installed, version 3.3. I’m able to save other admin changes – new posts, various settings, etc. – but get this error when trying to save Framework Options. Hopefully you can help. Thanks!

    Reply ↓

  33. hey Devin, is it possible to create subsections on the same tab instead of creating a tab per subsection.
    for example I have:
    home page background images
    about section bg images
    services section bg images
    …
    would make sense to be on the same page separated by a header

    Reply ↓

    • I’ve been thinking about adding the ability to have different meta boxes per page, but isn’t here yet. You could perhaps use the “info” option to create more separation.

      Reply ↓

  35. Great stuff.

    I have a question though, why does my child theme break? What am I doing wrong. Out of the options frameworks is looking for files in the child theme directory. How do I fix? Thanks.

    Reply ↓

  39. Hi Devin, great work with this one. Works a treat!
    I see that a few people have asked about css styles. Is there a way to link to the styles sheet instead of writing inline?
    For example, having the option to set all paragraphs within the main_content div of a site, rather than entering inline code to pull from the options.php to every paragraph within the main content div?
    Have downloaded the Portfolio Theme and had a look around in that but didn’t see anything.
    Maybe I’m missing something.
    Cheers. Chris

    Reply ↓

  41. hi Devin, great stuff, thanx!

    my question is about types. is there a way to save arrays of things? i.e. the admin would decide how many sidebars she wants (add a number in a text input) and that would build n other options in the same tab, where she would add a name for each. Then I’d initialise those in functions.php to make as many sidebars as desired.

    dont know if that makes any sense. maybe there’s another way to do that programmatically?
    thanx again for all the work.

    Reply ↓

  42. ok, i must be stupid (or need some sleep). or both. solution:

    options.php:
    …
    $options[] = array( “name” => “Sidebars”,
    “desc” => “Choose number of sidebars”,
    “id” => “sidebars”,
    “std” => “0″,
    “type” => “text”);

    $sides = of_get_option(‘sidebars’);
    for ($i = 0; $i “Sidebar $i”,
    “desc” => “Name sidebar $i”,
    “id” => “sidebars_$i”,
    “std” => “”,
    “type” => “text”);
    }

    functions.php:
    …
    $sidebars = of_get_option(‘sidebars’);
    for ($i = 0; $i ‘sidebars_’.$i,
    ‘name’ => of_get_option(“sidebars_$i”),
    ‘description’ => ‘No tiene descripción’,
    ‘before_title’ => ”,
    ‘after_title’ => ”
    ));
    }

    Reply ↓

  43. As an end user – In wp-admin, Theme Options will not save. It gives me the message that the Options are Saved, but they have reverted back to the defaults.
    The host is HostGator and the theme used is “Seventeen”if that helps. Any solution for this? Tried Google search, HostGator help line, and just generally messing around with it for a couple of hours.

    Reply ↓

  44. Hi Devin, it is possible to have more than one field hidden and then appear on the click of the check box as in your video?

    Specifically I’m trying to have a mini drop down array, and two color options hidden. Only appearing when clicking on the checkbox.
    I’ve tried adding the class ‘hidden’ to the drop down list array within the options.php but with no luck so far.

    Thanks

    Reply ↓

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>