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

You can find the “Options Check” theme referenced in the video on GitHub.

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

You can also purchase the Options Kit, which is a collection of starter themes, including Options Check.

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)
  • 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
Learn About the Options Kit

Additional Tutorials

Future Development

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

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 .

If you would like to donate to the ongoing plugin development you can purchase the Options Kit for $20 (which has helpful demo themes).

579 Responses

  1. Dave

    If you are a theme developer and you sell themes, wouldn’t the customer who buys your themes now have to download & install this plugin just to get everything working? Shouldn’t the options panel be baked into the theme like your options framework? I may be missing the point here :)

      1. Dave

        Thanks for the clarification Devin. Looking forward to the updates you have planned on your options framework. Really like the file upload fields and how they use WP’s upload functionality. Great work.

  2. Stu

    Best thing ever. Do you know of a quick workaround for having simple checkboxes added to an option. For example, I have an text field option for a link in which I want to add a checkbox below for the link target. I can do this very easily with your method but it creates a whole new option with a header etc for the checkbox… Is there any way to suppress the < / Option Name? This may be a good addition.

      1. Stu

        That makes sense. For now I just hacked your plugin with following:

        In Line 34 of options-interface.php

        change

        $output .= ''. $value['name'] .''."\n";

        to

        // hack from stu
        if($value['hideheader'] !="Yes"){
        $output .= ''. $value['name'] .''."\n";
        }

        In themes/themname/options.php just add another parameter


        "hideheader" => "Yes",

        Mind you I don’t recommend this method as it will be overwritten by plugin updates.

  3. Hi Devin – plugin looks great! I tested it in a Thematic child theme and here’s a thought:

    I was a little confused when making options for changing simple styles. I figured it out with the non-plugin Framework using style-output.php that pulls in the values from a dynamic stylesheet and passes them to a function called in optionsframework_wp_head(). For anyone interested, here’s my post about it.

    Is this method appropriate for the plugin as well? It might be helpful to add some more documentation or an example about it (for budding developers such as myself).

    Thanks again for the great work!

  4. Hey Devin

    I want to ask some issue. When I create a dropdown list to select categories in theme-option.php. It’s seem like:

    But it INSERT in to database same as anything show up in the form. Can I show all categories but just insert Categories ID???

    Thank you & wait for your reply.

  5. nice plugin, i like options style…i’ll modify for my theme development.
    but i have 1 problem…i cant add html code on textarea/text….

    any option to do that?

      1. i think will edit your plugin, then move it into theme folder….its much easier for my user. Thanx for hard work Devin, i not see any donation button or something similiar. I want share a cup coffee, cause i got benefit using this plugin…

      2. Great job, very useful plugin, thanks a lot for sharing!
        I also think that a way to add html code in textarea would be very useful. Hopefully you’ll find a good way to do it. Keep up the good work.

  6. I’m super excited to try this out! Sortable boxes would be a fantastic addition to this. For example; If you have a full-width blockquote, image slider, columnized widget area, the user could drag and re-arrange the order of how those things will appear on their front page.

    At any rate, thank you for sharing this :]

  7. Stu

    Any thoughts on how to avoid the add slashes issue with a textarea. I have a textarea option with an apostrophe in one of the words and it adds slashes. I can manually remove it in the code but was wondering if you had a better idea.

  8. will

    I set up the Select a Page option, and it looks like the page’s ID is stored and returned. How to I convert it back to the permalink/page slug when outputting it on a template page?

  9. I wanted to say thank you for sharing your knowledge on how to create options pages. I have been interested in learning how to do this. Your website and the YouTube video you posted are super helpful. I cannot thank you enough. I have been interested in setting up an options page with all the bells and whistles so it makes theming super easy.

    If you have any suggestions on how to learn how to insert image slides, functions for thumbnails, and other jQuery-type stuff, I would love a link.

    I am glad I stumbled onto your site. You are definitely bookmarked for future reference.
    Cheers,
    Susan

      1. I found this page which makes it look easy, and worked when I tried it on a custom theme options page of my own. However, I wasn’t sure how to integrate it into your framework. Maybe this will be of use to you:


        "a_nice_textarea"
        )
        );
        ?>

      2. Argh…the code tag doesn’t do what you think it will do in the comments. Anyway, the snippet is on that page linked to above.

  10. Joveth Gallardo

    First of all, thank you for this awesome plugin. I was wondering if ajax save function (like woo themes) would be included in future versions.

  11. Stu

    This is the greatest. I am having an issue when trying to migrate a site. I build sites on my local host but when I move them live I almost always lose all the theme options. I am literally just moving the database and all the files and then changing some config settings and of course some file paths etc… Any thoughts on what I am missing here?

  12. Dom

    Hi,

    What you did is brilliant! Many thanks. Although I am still new to all this stuff and was wondering how can I export values to my .php style sheet?

  13. Hi there.

    I’ve been playing with the framework for a couple of days now and I truly love it!

    However, there’s one thing that I can’t seem to make work properly. I’d like to move the “Theme options” link from the “Appearance” submenu to somewhere else, either to its own parent menu, or to another menu section (“Tools” for example). But when I do that, the image uploader stop working (nothing happens when I click on the “uplaod” button). Any idea what would cause this problem?

    As an example, here’s the code I’m using to move it under the “Tools” menu :

    $of_page = add_submenu_page(‘tools.php’, ‘Theme Options’, ‘Theme Options’, ‘edit_theme_options’, ‘options-framework’,’optionsframework_page’);

    And, the code to make it its own parent menu :

    $of_page = add_menu_page(‘Theme Options’, ‘Theme Options’, ‘edit_theme_options’, ‘options-framework’,’optionsframework_page’);

    Any help would be much appreciated. Thanks :) And keep up the good work with the framework.

      1. Charlie

        I second Matthew’s question. The uploader breaks with a top-level menu added.

        If we do something like:

        $of_page = add_menu_page('Theme Options', 'Theme Options', 'edit_theme_options', 'options-framework','optionsframework_page', '', 65);

        That puts the menu as a top-level right under the Appearance menu. Of course this breaks the uploader, but I’m not sure how to fix the option-medialibrary-uploader.php file.

        Any help would be awesome!

        Thanks, man.

      2. The URL when I have the theme options at top-level in admin;

        /admin.php?page=options-framework

        However, none of these efforts make the uploaders work in the medialibrary uploader page;

        $of_page= ‘options-framework';
        $of_page= ‘page_options-framework';
        $of_page= ‘admin_page_options-framework';

        Admittedly, I’m not a PHP wizz and don’t fully understand the naming convention in the original advice to Seb. What is eluding me, here?

      3. Charlie

        Again, same as Matthew. And I’m also not a PHP whiz. :)

        I’ve tried all those options as well and still no working uploader. I’m still using (in options-framework.php):

        $of_page = add_menu_page('Theme Options', 'Theme Options', 'edit_theme_options', 'options-framework','optionsframework_page', '', 65);

      4. Anthony

        Hey, Devin.

        I’m with Matt and Charlie. The URL path you suggested isn’t working. Well, at least not the way I have it. I’m also trying to get a top-level admin panel going, and I’ve exhausted pretty much all of the options I could think of.

        Please help if you’re still out there lurking :)

        Anthony

      5. Charlie

        Devin, you rock!

        That solution worked like a charm. Really appreciate you being out there and moderating the comments. Awesome support. And thanks for the instruction on how you came up with the solution…that’s very helpful.

        Keep rockin’!

        Best,

        Charlie

  14. i’m currently bashing away trying to make your clever theme and options plugin look as gracefull as it could. meanwhile…
    ooh! on your above demo portfolio press has option to use portfolio page as a front page… i don’t appear to have this option. it would be great!
    especially if it was possible to add a text/welcome message to a front page above portfolio grid.

    fingers crossed this will look great and work great too!

  15. Mike

    hi!
    updated on version 0.6 and the option “Uncheck this if you wish to manually display portfolio images on single posts.” does not work anymore.

    The picture is displayed in the post (neither if its checked or not)

      1. Hi Devin,

        I too have Portfolio Press 0.7.3 and Options Framework Plugin 0.6, but no matter which option I choose I cannot seem to get around the featured image being automatically inserted into the Post.

  16. Hi, I have two questions and would appreciate some help please…

    (1) How do I change the “Theme Options” title in the admin interface to “Front Page Options”?
    (2) Is it possible to bring the standard “Thematic Options” into the new menu, so that I don’t have 2 options pages: standard thematic and new.

    Thanks in advance
    David

      1. David Hedley

        Hi Devin, thanks for the reply. If I unhook the standard Thematic options do you know what I would need to edit in order to add these footer options to the new custom options page?

        Also, I’ve just come across an issue with using a text area, whereby it will not hold or tags. Can anything be added to the options page to ensure all html is parsed?

        Thanks again

      2. Hi Devin, perhaps my last reply should have been a bit more constructive! I added the default filter override exactly as is, but am not sure how and where to add the allowed HTML tags and what format they should take within the script. Could you please provide an example for the tag.
        Thanks in advance
        David

  17. Sahin

    Hi Kevin,

    The previous version of options framework had auto-detect styles in styles directory and give it as an option to switch between on theme options page. The new version seems not to have it or am I missing something?

  18. Ray

    Looks very nice!

    I’m probably going to mod the Options Framework so it’ll work for a plugin’s options instead of a theme. Would be great if you could add some filters in your framework in a future version, so it would be simple to switch between the two.

  19. MBT

    I’m trying to create a dropdown list to select MULTIPLE categories and then use this options in the query_posts. Can anyone help me?

      1. Allen

        I write like this, it works on the admin panel, but I don’t know how to output the code, can you help me? just like MBT said.

        $options[] = array( "name" => "Select some Category",
        "desc" => "Passed an array of categories with cat_ID and cat_name",
        "id" => "multi_categories",
        "type" => "multicheck",
        "options" => $options_categories);

      2. Allen

        I write like this:
        if ( is_array($multicheck) ) {
        foreach ($multicheck as $key => $value) {
        // If you need the option's name rather than the key you can get that
        $name = $test_array_jr[$key];
        // Prints out each of the values
        if($value==1)
        {
        echo '' . $key . ' ||';}
        }
        }
        else {
        echo '1';
        }

  20. This is amazing, been messing with it for several hours now. One workaround I cannot figure out though. Say I want the client to be able to upload something like a pdf and embed the download link in the header so the visitor of the site may then download this pdf. Is this doable?

      1. My workaround thus far is to go in to the options panel and use the uploader to upload a pdf insted of an image, so that worked. Then I went and changed this:

        <img src="” />

        To this:

        <a href="”>File

        It works for me! Thanks again for this awesome framework. It is really a joy to use, great screencast as well.

  21. Hi,

    I need to uninstall this plugin from one of my sites. Other than deleting the files via ftp, is there anything that will remain in the database that I will need to delete manually, and if so, what?

    Thanks
    David

  22. Hello!

    This article is great! But I was wondering, I installed the “options framework plugin” and it worked just fine… but when I installed a new theme from the same company, now the plug-in states:

    “No Options Are Loaded

    Your theme doesn’t appear to support the Options Framework yet.

    If this is a mistake, make sure that the file options.php is in your theme folder and that you have the correct theme activated.”

    …Which is not the case. I haven’t received response from the theme support yet, so I was wondering if you had any ideas? Thanks!

  23. shawn

    Wow, thank you so much. Finally the ability to use the woo concept admin, which I have used for years, without all the bloat.

    Question:
    One thing I have asked woo for, with no answer yet, is to have the ability to have an image field insert, where you can insert an image, and then another box appears ‘insert another image’, thus allowing me to have multiple image inserts in a single field.

    example:
    Woo uses image fields for sliders, but you are forced to a limit of 5x or 10x etc… “I know I can manually add or remove more but that is not the point”.

    Any chance you would consider adding this type of functionality?

    *A great example is the farinspace meta class, which has this ability for metaboxes. I use the class to create post image sliders, where the user can have a different number of images in the slider on a per-post basis. Would be nice to bring the same functionality to the theme admin, for theme sliders.

      1. shawn

        I like the idea of having 10 and hiding the ones not used. Is this something you would consider adding in, or posting a code snippet on how to accomplish this?

  24. Charlie

    Hey Devin,

    Quick question for you hopefully. Trying to use the multicheck but having some difficulties. The following code isn’t working for me:

    The output of this code is either “0” or “1”, depending on whether the box is checked or not. I can’t get the “no entry” or any “else” statement to work at all.

    Ideas?

    Thanks, Devin!

  25. Charlie

    Sorry…that comment didn’t print right. Was talking about this:


    if (isset($multicheck['one']) ) {
    echo $multicheck['one'];
    } else {
    echo 'no entry';
    }

      1. Charlie

        Appreciate your feedback, Devin. Always good to reach a live human out there :)

        I’ll check out your suggestions.

        Best,

        Charlie

      2. Charlie

        All right, Devin, I read through your articles and such and am still running into trouble.

        Here’s what I’m trying to do (well, not really but a silly example that fits):

        I want there to be one heading in my theme options for Breadcrumbs, under which will be a multicheck for “Posts” and “Pages” so the user can select either or both to show breadcrumbs.

        Now, I’m just not sure how to pull those in and check for “checked”. Regardless of the method I use, I’m not really getting a boolean behavior, but rather an always “checked” result whether the box is checked or not.

        I’m using the theme version of the framework and not the plugin, and just this morning I pulled down the latest builds from Git. So…I should be up to date. Also, tried all of this on a new install that hadn’t seen this before, and still no go.

        So my question is…finally :)…how the hell do I check the for “checked” or “true” or whatever is needed, and then echo a result based on that?

        Thanks again, man!

        Charlie

      3. Charlie

        Thanks, Devin, but isn’t that for checkboxes only? I’m using those just fine. What I’m having trouble with are the multicheck options.

  26. adam

    Hey great plugin and framework! I am currently setting up the framework on a multisite install and getting an error with the uploader. it uploads the file fine and I can browse to it under media. It even shows the image after uploaded on the theme options page.

    The problem begins when i hit save. The image disappears from the theme options page and does not render in my template where i have put the proper of_get_get_option call. Any suggestions for where to begin with troubleshooting this ?Thanks!

  27. Thanks for the awesome plugin Devin! I’ve used it for every client site, it really has made life easier.

    Right now I’m trying to figure out how to edit a theme option on the front end for a special use case. I was thinking that I could use a function similar to update_post_meta but obviously for the options table. Do you have any recommendations on what hook I could use?

  28. Hi, thanks for this amazing plugin! Really useful stuff:)

    I’m trying to find a good way to use thumbnail sizes on images uploaded using this, the only way I can find is to add something like

    function theme_setup() {
    add_image_size( 'theme-main', 440, 170, true );
    }
    function get_attachment_id_from_src ($image_src) {

    global $wpdb;
    $query = "SELECT ID FROM {$wpdb->posts} WHERE guid='$image_src'";
    $id = $wpdb->get_var($query);
    return $id;

    }

    to functions.php then


    //get the url of the image
    $image_url = of_get_option('example_uploader');
    //find id from url
    $image_id = get_attachment_id_from_src ($image_url);
    //get thumbnail src, theme-main is my custom thumbnail size
    $image_attributes = wp_get_attachment_image_src( $image_id, 'theme-main' );
    echo $image_attributes[0];

    in the theme. Is there a more direct method that I’ve overlooked?

  29. Also, just noticed this in options-sanitize.php

    function of_recognized_background_repeat() {
    return array(
    'none' => 'No Repeat',
    'repeat-x' => 'Repeat Horizontally',
    'repeat-y' => 'Repeat Vertically',
    'repeat' => 'Repeat All',
    );
    }

    should be no-repeat rather than none

  30. Axel

    Hello Devin, thank you for the great plugin !

    Images for layout have labels ( $output .= ” . esc_html( $key ) . ”; )
    but I can’t print them somewhere around images.
    Right now I added title to images to have some indication.
    Can you help me here, please. I’d like to have layout images labeled.

    Thank you.
    P.S. Is there a forum for this plugin, someplace ?

  31. Kevin

    Hi, Devin. Really cool plugin! Quick question, though: Is there a way to override the list of fonts in the typography dropdown without editing the plugin? I want to use it to select a typeface from Google Web Fonts.

      1. Kevin

        Brilliant! I learned something new today. Thanks for your help. In case anyone is interested, here’s what I put in my functions.php file to filter the font list:

        function mpw_recognized_font_faces( $default ) {

        // put your modified font list here
        $default = array(
        'arial' => 'Arial',
        'verdana' => 'Verdana, Geneva',
        'trebuchet' => 'Trebuchet',
        'georgia' => 'Georgia',
        'times' => 'Times New Roman',
        'tahoma' => 'Tahoma, Geneva'
        );
        return $default;
        }
        // override the plugin's function with ours
        add_filter('of_recognized_font_faces','mpw_recognized_font_faces');

      2. Kevin

        Hey, Devin. I found two other things I’d like to be able to do that the plugin may not support:

        1) It would be great to be able to hide the font-face and style dropdowns by filtering them to have no values. This would be useful if we want to let the user select a font but not a style, for example.

        2) On the font size dropdown, it would be great to be able to filter it at all. There’s not apply_filters call on the function that does that dropdown so we only have access to the default values.

        If I’m overlooking a way to control these two issues, let me know. Again, the Options Framework plugin is awesome!

        Thanks!

  32. Great plugin. Just started working on a website for a client. Trying to figure out if 2 things are possible.

    1. Integrating with the WPML plugin to allow for some content to be translated
    2. with a drop down, if 3 is selected and saved if then 3 fields could appear on the options page.

    Thanks again for all your hard work.

      1. Hi Devin,

        Yea I realized I could get it done by getting the strings worked out. But having never done that before it’s slow going.

        I hadn’t thought of the hidden check box option cause when I copied the option.php file into my theme nothing happened. Will investigate using that some more.

        Thanks

        Oh and is the tab on top interface new? cause your video has the tabs on the side

      2. Guess my issue with the translation is I’m not sure how to add the _e( & __( string options to code like

        All it seems to need is that right string.

Leave a Reply

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>