Options Framework Plugin

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

Although this plugin is still maintained and secure, the recommended way to add theme options for new themes is to use the Customizer.

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 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.

Available Options

These are the options available:

  • 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)
  • editor

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 your 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.

Download the Plugin

Download from WordPress Repository
Download Development Version

Additional Tutorials

Future Development

This plugin is not actively developed. If there’s compatibility or bug fixes needed, let me know.

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 on GitHub, including @mfields, @helgatheviking, @celtic7, @samargulies, @mattweibe, @Mamaduka and any others.

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

669 Responses

  1. web-dev

    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!!!

    1. Devin

      Yes, download the “Options Check example to see how to output checkbox info. e.g: if (of_get_option(‘example_check’,0) ) { // output some html }

      Donate links are in the sidebar and bottom of post.

      Glad you’re finding it useful!

      2. Devin

        Not technically necessary. Should default to false: function of_get_option($name, $default = false) if the option hasn’t been saved yet and is null.

  2. AJ

    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?

    1. Devin

      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.

      1. AJ

        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. Ana

    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

  4. elba

    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.

    1. elba

      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.

      2. elba

        However the above mention hack works, somehow it stops the image upload function to work. Can’t figure out why. Nothing happens when clicking on the upload button. :(

  5. Theresa

    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.

      2. Theresa

        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.

      3. Devin

        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. Richard

    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

    1. Devin

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

  9. Gotfers

    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 ?

  10. Angelus Lee Isaacs

    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 :)

  11. Audi

    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!

    1. Devin

      I’d guess that it has to do with $optionsframework_settings[‘id’]; in your options.php. This can’t have any spaces or strange characters. Try manually setting to it to something like ‘mytheme’ and see if your options save out.

  13. George

    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.

  15. manoj

    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

  16. Anthony

    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

    1. Devin

      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.

      2. Devin

        Yes, you’re doing it slightly wrong. Look at the Options Check theme for an example. Look at how “$test_array” is set up with keys => values. Do it that same way.

  17. Claudia Bohringer

    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

  18. Jeff

    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.

  19. Allen

    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
    });
    });

  20. Allen

    ??
    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>

  21. Phil

    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.

      1. Phil

        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’)
        );

      2. Devin

        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. Stu

    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.

    1. Jamz

      Also I want to know, this function is very useful! I have seen some theme options can backup and restore the options.
      Hope Devin can develop it.

  25. AC

    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

      1. elba

        I’ve checked the functions.php, checked the ids and everything, but it doesn’t seem to work? Any suggestion?

  26. Jon

    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.

    1. Devin

      Oh wait, sorry, misunderstood the question. It’s possible to display in a dashboard widget, but you’d have to hack it quite a bit. Might be easier just to start from scratch with your requirements.

  27. Ben

    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.

  28. Don

    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?

  29. leon

    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

  30. Flo Nelson

    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.

  31. Andrew Dushane

    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!

  33. Paul

    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

    1. Devin

      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.

  35. Simon

    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.

      1. anemoone

        When I switched to the easel theme, an error ocurred in the admin panel. I couldn’t reach any admin menu page from the dashboard level. I had the announcement about an error in the directory where the plug-in was.

      2. Sylvain

        Hi Devin,

        I’m using the Options Framework Theme, thanks a lot for your work !

        There’s something where I get stuck though : the text (and style) I put in the text editor doesn’t save, and therefore nothing displays in my site when using

        Any idea where that could come from ?

        Thanks !

  39. Chris

    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

  41. sergi

    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.

  42. sergi

    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’ => ”
    ));
    }

  43. Jonathan

    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.

  44. Chris

    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

  46. Signo

    Hi Devin,I have a suggestion to allow the options menu to be placed anywhere the developer wants, the trick is to add a filter for the menu options. You just need to change optionsframework_add_page functions with something similar to this:


    function optionsframework_add_page() {
    $menu_Opts = array();
    $menu_Opts['parent_slug'] = 'themes.php';
    $menu_Opts['menu_title'] = 'Theme Options';
    $menu_Opts['capability'] = 'edit_theme_options';
    $menu_Opts['menu_slug'] = 'options-framework';
    $menu_Opts['icon_url'] = null;
    $menu_Opts['position'] = null;

    $menu_Opts = apply_filters('of_add_menu', $menu_Opts);

    if ( is_array( $menu_Opts ) ) {
    if ( '' == $menu_Opts['parent_slug'] ) {
    $of_page = add_menu_page($menu_Opts['menu_title'], $menu_Opts['menu_title'], $menu_Opts['capability'], $menu_Opts['menu_slug'],'optionsframework_page', $menu_Opts['icon_url'], $menu_Opts['position']);
    } else {
    $of_page = add_submenu_page($menu_Opts['parent_slug'], $menu_Opts['menu_title'], $menu_Opts['menu_title'], $menu_Opts['capability'], $menu_Opts['menu_slug'],'optionsframework_page');

    }
    }

    // Adds actions to hook in the required css and javascript
    add_action("admin_print_styles-$of_page",'optionsframework_load_styles');
    add_action("admin_print_scripts-$of_page", 'optionsframework_load_scripts');

    }

    after that we only have to add the of_add menu filter to place the menu in any place we want, like this:


    add_filter ( 'of_add_menu', 'signo_of_add_menu');
    function signo_of_add_menu($menu_opts) {

    $menu_opts['parent_slug'] = ''; //tools.php';
    $menu_opts['menu_title'] = 'Signo';
    $menu_opts['capability'] = 'edit_theme_options';
    $menu_opts['menu_slug'] = 'signo_menu';

    return $menu_opts;
    }

    1. Devin

      One of the guidelines of the theme review team is:

      “Themes are required to use the add_theme_page() function to add the Theme Settings Page to the Appearance menu, rather than using add_menu_page() to add a top-level menu.”

      See: http://codex.wordpress.org/Theme_Review

      I try to adhere to the UI recommendations of WordPress core- and since the framework is really only applicable for theme options it doesn’t really make sense to be able to filter the location to anywhere other than the appearance menu.

      If you do need top level menus, or multiple menu items, I’d suggest using the theme version of the framework and altering it to fit.

  47. Adam

    Wow! That what a great plugin! What do you think about creating a drag-n-drop interface for theme creators to visually create the Theme Options page instead of coding it?

    I’m sure code will still be necessary to input into a theme itself to output the options on the front-end. That isn’t a big deal since that’s what’s involved in creating a theme anyway.

    Thanks!

    1. Devin

      Yes, I’ve thought about creating a theme options generator before but never got around to it. I’ll keep it on the list of ideas to implement when I have time.

  48. David Nordström

    Hello,
    When I try to get into the Theme Options on my site it says that I have to install the options framework plugin to get that to work. I have done so and it still says I have to install it, even though it actually is installed.
    Could there be a problem with my server?

  49. David

    Hi Devin, sorry for the newbie question, but exactly is the right way to use the body background options?

    I did a little if funcion into my header.php

    if $bacground is a color echo
    else if $background is an image echo <body style="background-image:url($background['image']……..
    else echo

    But I really don’t like to use inline styling…
    Thanks :)

  50. GJ

    Great framework for options, but is there a version with the tabs going down (vertically) instead of across the top? I’ve seen this before but don’t know how to code it to do that. Thanks in advance!

    1. Devin

      You can look at earlier versions of the Options Framework (in GitHub), but I would recommend sticking with the tabs on top unless you’re really comfortable recoding it.

Leave a Reply