Options Framework Theme

The Options Framework Theme has all the code included to build a out a full featured options panel. It’s a bundled version of the Options Framework Plugin for those folks who want to build the options directly into the theme (rather than relying on a plugin).

This project was released long before the Customizer was a part of WordPress. The Customizer is now the recommended way to add theme options and you can read more about it here.

Available Options

  • 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

Instructions

Copy the “inc” directory, options.php, and the code snippet in functions.php from the “Options Framework Theme” into the theme of your choice. Hack away. You can also watch the video above to see how it is done.

When to Use Theme Version vs. Plugin Version

The code is 99% the same between the plugin and theme version. If you can do what you need with the plugin version, I think that’s the best route. If you find that you need to make significant modifications that aren’t possible with the plugin, go ahead and use the theme version.

Change the Menu Location

It’s highly recommended that you leave theme options under the “Appearance” menu where users expect them.

But, if you do decide to change the menu location it will break the media uploader. This is because the media uploader scripts are enqueued on $of_page= ‘appearance_page_options-framework’ in options-medialibrary-uploader.php. If you change the name or location of the menu, you’ll need to update the hook to be accurate, e.g. $of_page= ‘toplevel_page_options-framework’ and those scripts will load properly again.

Sanitization Filters

If you’re interested in how the options data is verified, or if you’re wondering why your script and embed tags are stripped out in the Options Framework, read this post.

Can I Use This Code in Commercial Themes

Yes! This code is 100% GPL. Please read the included license for more details.

Development Version on GitHub

The development version of the Options Framework Theme is available on GitHub.

Additional Tutorials

The demo themes associated with these tutorials are also available on GitHub.

866 Responses

  1. Rob

    Hi Devin,

    Awesome coding you’ve done here!

    Can I just check though – in your example index.php for the ‘options check’ template (https://github.com/devinsays/options-framework-plugin/blob/master/options-check/index.php) you have the options called like the following:

    If no entry is made for a given option, should this output the ‘no entry’ text (similar to the way get_option outputs a default)?

    The only way I can get a simple default value to show at present is using something like:

    Thanks

  2. Oren

    Hello Devin,
    I’m loving this, really great job.

    I have a question if it’s OK to ask.

    I added 10 options of the type “text” where the user needs to fill URLs.
    They are not mandatory. Meaning, the user will fill the text fields that are relevant for him.

    In the theme itself, I check each of these field, and if they are not empty, I display their output.

    What I want to accomplish is letting the user to decide the order they appear in the site.

    Any suggestion of how can I accomplish that? Any direction would be awesome :)

    Thanks in advance
    Oren

  3. sin

    Hi Devin,

    is there a way to filter optionsframework_tabs, to make it unordered list or something, or to add custom types to optionsframework_fields?

    I don’t want to make changes directly?

  4. Fred

    Hi, your plug-in is very useful, however I don’t understand how can I add an option that let me switch between different stylesheets, is there a way?

    Thank you

  5. Tom

    Hi Devin,

    thanks for your amazing framework! Really useful and loads of fun to play around with.

    I’d just like to clarify the use of this in themes for resale. I know the license is GPL so very flexible legally. What I’d like to know is would you be personally happy for your options code to be used in an otherwise original theme to be sold on a site like themeforest?

    Thanks!

    Tom

      1. Tom

        Great, thanks Devin!

        I meant flexible compared to a commercial license, I didn’t really manage to articulate that very well.

        Theme Forest license all wordpress realated php as GPL but theme Javascript and CSS are a commercial license. Is this okay or would all need to be GPL?

        Cheers,

        Tom

      1. Alex

        In Typography there is a text: Some sample text in your style. I can see the changes in face, style and color but not the size.

  6. Dear Devin,

    Tim here, I have come across a plugin that disables the wp theming options framework.

    The plugin is called Coffee Admin Theme.
    It takes all the default values and strips them out and replaces them all with the letter “a”

    And none of the options work.
    Might be something you may want to look into.
    Thanks
    Tim

      1. I deactivated the plugins one by one and no other plugin caused any errors to the options frame work so I could only deduct that it was the above Coffee Admin Theme,

        could there have been something I missed.
        Thanks
        Tim

  7. sin

    Hey Devin,

    I’m trying to get my theme working with wp customizer. I made layouts option using radio/image option picker, and everything’s ok in theme options. Then I added code for layouts to appear in customizer, everything’s good there too, except options are not saving.

    This is the part where option should be updated in customizer:

    ‘settings’ => ‘themename_in_db[site_layout]’,

    Is this possible with of?

    Thank you very much anyway!

      1. sin

        I found the problem. Looks like options framework is overwriting what’s in theme customizer. Here’s what’s happening:

        I added code for the “example_text_mini” to appear in theme customizer.
        Everything’s ok, you can see “example_text_mini” text in customizer. I type over that text (it’s type text), and it get’s overwritten in preview. Ok.

        When I hit save, it loads the old “example_text_mini” value.

        So, I installed some other theme (doesn’t have theme options), to test things out.
        Then, I added again the same code for customizer to load options from my theme based on options framework. It loads “example_text_mini” option to customizer, and I can change it, save it and everything’s fine.

        But I can’t make it work with my theme. Any ideas?

        Here’s the code I used, just change the “themename_in_db” with your option table name and it will work.

      2. sin

        Forgot to mention, if it will make you faster to understand – value from theme customizer get’s replaced with option std from options.php in db.

      3. sin

        Hey Devin,

        you might tested just changing options values only in the customizer? That works for me too, even if I click save there, it get’s “saved”, but only there, not in theme options.

        I don’t have theme options and customizer opened at the same time, I tested all combinations – with both opened, customizer opened, then saved, went to theme options and I see std value there. And when I get back to customizer, std is there, like in theme options. I hope you understand me.

  8. Alex

    In Typography there is a text: Some sample text in your style. I can see the changes in face, style and color but not the size. Thanks.

  9. Kirsten

    Hi, Devin!

    I’m just fiddling around with your framework and I love it.
    I need a options page for a theme I made for a client. Using the framework it’s a piece of cake.

    I had a little difficulty understanding the meaning of the “plugin version” and the “theme version” and so I did a bit of googling and found this article by Dave Clements.

    In the comments there is a discussion about the Settings API and how the Options Framework handles it.
    Unfortunately I don’t quite understand the point, I’m not an expert in coding.

    You answered the question whether the code is using the API somewhere above:
    “Partially. Fields aren’t outputted in the standard Settings API way (tables), but otherwise yes.”

    What does this mean? Are there any pitfalls concerning further WP-versions?
    I’m just trying to get a feeling for it.

  10. Kirsten

    I did and meanwhile I got it. :-)
    I think the hard thing is to understand that the theme is just a demonstration. It’s confusing because I would expect to see some basic theme with the options inside.

  11. Jonathan

    I’m a theme developer and i use options framework on all of my themes and today on wp 3.4 i turned on the wp_debug mode and found a deprecated code in options framework so i decided to visit this website once again to download the latest version and i was so happy to find out that a new feature called text editor was included in the options framework.

    I love your work men! i was thinking of donating later a few bucks to support this project so it will be developed further for others to download for free.

    Jonathan

  12. jonathan

    Also Found an Error when saving the values, it says at line 283 no defined function

    $options =& _optionsframework_options();

    it had an underscore and i remove it and it worked. please update your file.

  13. Jebbo

    Great options panel! Thanks for your work on this.

    Quick issue I’m dealing with: I have gotten everything setup, but when I try to save the options, I get a blank white screen. I’ve gone through the options.php file carefully and don’t see anything that could be causing this issue.

    Any thoughts on what might be causing this?

      1. jebbo

        Thanks for your prompt reply. I removed the underscore (as Jonathan noted) and it works perfectly. Just downloaded from Github yesterday, in case you’re wondering about the source.

  14. shawn

    Is there a stylesheet available that will move the tabs in the admin panel to the side vs. on the top of the page? (ala woo)

    Working on building a responsive admin stylesheet as WP backshelved it for now and I am finding that on smaller devices there just isn’t enough room on the top for more than 3-4 tabs.

    Also:
    Been using Lee Masons NHP framework with fully utilizes the WP settings api. Am I right to guess that the options framework also uses the settings api and stores all values in the standard WP table?

    *should I ever change the framework, I don’t want to have to pull my data from a sep non WP table.

  15. Tomas

    Is there a way to accept JavaScript in textarea?

    I have analytics textarea in my theme and when I insert the code, the script tags are stripped away.

    Great work on the framework, thank you very much!

  16. shawn

    Couldn’t find any info on this:
    1. Is there a ‘repeater’ field type, ala ACF repeating fields?
    – I need to be able to ‘replicate’ a single or group of fields by clicking an ‘add new’ button.
    2. Is there drag n drop ability coming soon?
    – saw the 3 month old ticket on git where smof uses drag n drop to be able to ‘order’ fields on a layout type setup.

      1. Devin, I like your idea of a generic plugin that can export/import ANY theme option. In the weeks since you posted that comment, have you become aware of anyone developing such a plugin that works with the Options Framework? I’ve created such a robust theme options panel using the framework that I’ve concluded I probably need a way to save the options to a backup file and restore them if necessary.

      2. Jessica

        Hi Devin,

        Seems like a repeater field wouldn’t be *too* difficult, could you just add the options using javascript and put “[]” in the field names?

  17. Javier

    When I install my theme in a new and clear installation, the theme looks ugly. It doesn’t load the default options from the options framework until I save the options. What am I missing?

      1. Hi Devin,

        Regarding my other recent comment, it seems to be related to this previous issue as posted by @Javier. Your reply was as follows:

        “Whoever developed your theme probably didn’t provide defaults in their of_get_option calls, so the theme won’t properly work until defaults from the options array are saved into the database.”

        This idea of having defaults defined in two places really doesn’t seem practical to me. The defaults are defined in options.php and I really shouldn’t have to define them in the individual template PHP files as well – this would make updating and maintaining the theme a real pain.

        The logical solution would be for the default options values in options.php to be saved to the database when the theme is initialised / used for the first time. Can you please advise how I might do this?

        Thanks,
        David.

      2. Hi Devin,

        Thanks for responding so quickly. I’ll definitely give optionsframework_setdefaults() a try.

        I’m not convinced about what Otto says – the brief quote offers no justification for his statement. All the settings are going to be stored in the database the instant the user makes even the the tiniest edit anyway, so I see no harm at all in preempting that and ensuring the settings are stored & retrieved in a consistent way, with only one file to store the defaults instead of having to set each default twice, in a massive number of different locations in a huge number of different template files, as well as in options.php. I think that’s unsustainable development, but of course that’s my opinion.

  18. Marie-Elaine

    Hey! just want to say that I really like your Options Framework. I translated to french if you’re interested. I also changed the “text domain” in two or three spots where it wasn’t set to “options_framework_theme”.

  19. Azhari Subroto

    Nice improvement btw,

    I have question for you.
    Have you any idea to make “ajax save”? So, whenever we hit the save button, it will not refresh the whole page. Just like wootheme option panel.
    thank you.

  20. Hi Devin,

    I’m creating a number of themes using options framework built in to the theme. I have a curious thing happening: when I first install the theme, the website looks broken, as if it’s not picking up the theme options. Then I go into the options screen, click ‘save’, reload the website and all of a sudden everything looks OK.

    Any idea where I’m going wrong?

    Cheers,
    David.

  21. Lore

    I just spent about 12 hours trying to make an MCE editor in the theme options save to database. So your solution makes me very happy! Plus, now I don’t have to figure out the next 12 things I planned.

    As a UI designer and developer, I rarely find something that makes me this happy. Thanks so very much.

      1. Nauman

        Devin i got that working with same logic as you defined for “Sidebar Position”.

        i have one more question

        you have used in logo

        “class” => “hidden”

        to hide upload and logo width options i copied same code but its not working for me can you please tel me how it works..
        Thanks.

  22. Towfiq I.

    Devin,

    How can we translate the output of the theme options with a translation/multi language plugin? I am getting complain that they are not being translated.. do you have any idea bout how to make them translatable? for example like this maybe:

    Let me know!
    Thanks

    1. Towfiq I.

      I was talking about the theme options output not the theme options label. For example if I add a text field in my theme options the output on frontpage cannot be translated with any kind of wpml/qtranslate plugin but the plugins can translate everything else. do you have any suggestion? Am I missing something? I added a code in my comment earlier which is missing can you take a look.

      And Do you have any other payment options to donate other than paypal. I want to donate but I dont have a pypal account. My country is not yet supported. :(

      Thanks

      1. mbt

        Hi Towfiq,
        I just saw your post and I have the same issue than you with output fields and WPML translations. Did you get to translate this fields? How did you do?

  23. Lorenzo Lamas

    Hello,
    Great work. really useful!
    I’m a beginner and i have a question. I did create my own theme from scratch, and now, i wanted to install/use your framework. I installed it in my theme as shown in the video.
    The thing is, i created the tabs and fields for the theme customization but i didn’t understand how to make it work.
    For example, i created a “field” to change the header background color, but i didn’t understand how to make it work (to apply the change on the theme).
    Do you have a video tuto or an example that could help me understand?
    Thank you

  24. Hi Devin,
    I am a complete newbie at plugin development, and when I have come across this, I got an “aha moment”. Can I use this for options of plugins that I make for WooCommerce?

    Ciaran

  25. Hey there – I purchased this package and am loving it so far. One thing I noticed though is that the hidden text inputs that fade toggle are not very dynamic with the jquery. For instance, my theme will have social media icons but not everyone wants to use all icons. So there will be check boxes for the icons they want to use in the options panel. If they check a box the hidden field will appear for them to enter the URL to their profile. Right now if I wanted many different options and corresponding reveal text fields I would have to rewrite your example jquery on click method many times. I figured this wasn’t very good, one simple click method should work fine for all. Here’s what I did:

    1. Added a class ‘reveal-text’ to all toggle checkboxes.

    2. Added a class ‘hidden’ to all corresponding toggle inputs

    3. Coded some jQuery to climb up DOM and target next corresponding hidden field:


    //hidden text
    $('.reveal-hidden input[type="checkbox"]').click(function() {
    $(this).parent().parent().parent().next('.hidden').fadeToggle(400);
    });

    if ($('.reveal-hidden input[type="checkbox"]:checked').val() !== undefined) {
    $(this).parent().parent().parent().next('.hidden').show();
    }

    Again, great resources here. Compared to most options panel this one is the most clean and uses Settings API nicely. Hopefully we’ll get a more elegant solution for multiple hidden text toggles but this will do for now!

      1. RoManuV

        I extended this solution (from issue #113) so that it can show/ hide several controls (regardless of their types) by checking/ unchecking a single checkbox, as follows:
        1. I added a “parent” attribute to each hidden field, whose value must be the ID of the checkbox:

        $options[] = array(
        'name' => __('Check to Show a Hidden Text Input', 'options_framework_theme'),
        'desc' => __('Click here and see what happens.', 'options_framework_theme'),
        'id' => 'example_showhidden',
        'class' => 'has_hidden_child',
        'type' => 'checkbox');

        $options[] = array(
        'name' => __('Hidden Text Input', 'options_framework_theme'),
        'desc' => __('This option is hidden unless activated by a checkbox click.', 'options_framework_theme'),
        'id' => 'example_text_hidden',
        'std' => 'Hello',
        'class' => 'hidden',
        'parent' => 'example_showhidden',
        'type' => 'text');
        $options[] = array(
        'name' => __('Input Radio (one)', 'options_framework_theme'),
        'desc' => __('Radio select with default options "one".', 'options_framework_theme'),
        'id' => 'example_radio',
        'std' => 'one',
        'parent' => 'example_showhidden',
        'type' => 'radio',
        'options' => $test_array);

        2. I added the parent name as a class, in the generated markup (the function optionsframework_fields() in class_options_interface.php):

        ...
        // Wrap all options
        if ( ( $value['type'] != "heading" ) && ( $value['type'] != "info" ) ) {
        ...
        if ( isset( $value['parent'] ) ) {
        $class .= ' ' . $value['parent'];
        }
        ...
        }
        ...

        3. I modified the options_custom.js as follows:

        // checkboxes with several hidden inputs
        $('.has_hidden_child').find('input:checkbox').each(function(){

        if ( $(this).is(":checked")) {
        $parent_name="."+this.id;
        $(this).parents('.section').nextAll($parent_name).show();
        }

        $(this).change(function() {
        $(this).parents('.section').nextAll($parent_name).fadeToggle(400);
        });

        });

  26. Closer

    Hi, looking for some advice please – I’m using a theme (bought on Themeforest) that contains your Theme Options panels and when I click ‘Save settings’ after changing things they are not saved and just default back to the original setting? The theme author is completely stumped and doesn’t know why it is doing this…dont suppose you might have any ideas as to why the theme options might not be saving?

    Any help you can give me would be much appreciated!! :)

      1. Closer

        Thanks for your reply!

        The author/thread where they discuss your options framework is here – http://www.goldenworks.eu/support/topic/theme-options-not-saving – I’ll post up a new reply saying that you’ve asked that they get in touch.

        I haven’t changed the theme name nor make any customizations at all…I was scared that would break things so I just uploaded it as is to test it and it didn’t work.

        I’ve also been in touch with my server company (the theme authors thought it may be a permissions issue, but everything there seemed ok there) and they asked if any theme elements used http loopbacks…does your theme options framework use them?

        Once again, thanks for your help – I’m trying to build a site for a client and if I can’t get this theme to work I’m a bit stuffed! :(

    1. Rifki

      Hi Closer,

      I’m also using Options Framework for my themes and some of my users also having this issue, It can be fixed by re-install the WordPress installation with manual install method.

      I don’t know what exactly the problem but for some case the theme options won’t save the options because you’re using script installer such as fantastico to install the WordPress, it’s no problem if you’re using SimpleScript.

      Rifki

  27. Patrick

    Hi,

    great framework. I have a question, I don’t figure out how to get the meta (alt, description,etc) from an image upload with the “uploader”, you don’t save the ID but the URL of the image. Do you have an idea?

    Thanks, continue your great work.

  28. Hi! I’ve been playing around for some time with your framework, it works great! But today i’m trying to implement a “multiselect” solution over the select list. I’ve got the multi select (from jquery ui) to work but when I try to save the values nothing happens (the values aren’t stored).

    Could you help me out with this, it’s killing me!

    Great work with your plugin, thanks for everything.

  29. Pete

    Hi Devin, I was hoping I could revisit a feature request. The ability to choose a post as well as a page, or both. You argued last time that the number of posts would mean too many queries on the db.

    This options plugin is awesome for small business websites that use WordPress as a CMS where they still use posts but they have a limited number <50.

    This plugin has a feature whereby you can choose any tag, and in theory there are normally more tags than there are posts.

    For all of us who don't have a large number of posts, and would love a drop-down feature to choose a page, or a post or both would you reconsider this feature, or show us a patch we can use.

    Thanks,

    Pete

  30. Hi, Great framework, thanks for the contribution.
    Any ides why shortcodes e.g. [shordcode] do not work in the theme option fields. Maybe it get sanitized? Maybe it’s just me?

    Thanks

    Sasha

  31. colin

    Re: “Display admin menu link only if user has permissions”

    i have a strange situation where i need to do the opposite – restrict access to posts and pages for all users, and only allow access to Options Framework. any easy solutions for this?

    1. colin

      I really should spend more time looking for solutions before i post up here. sorry.

      i’ll use this :
      function remove_menus () {
      global $menu;
      $restricted = array(__('Dashboard'), __('Posts'), __('Media'), __('Links'), __('Pages'), __('Tools'), __('Users'), __('Settings'), __('Comments'), __('Plugins'));
      end ($menu);
      while (prev($menu)){
      $value = explode(' ',$menu[key($menu)][0]);
      if(in_array($value[0] != NULL?$value[0]:"" , $restricted)){unset($menu[key($menu)]);}
      }
      }
      add_action('admin_menu', 'remove_menus');

  32. Bryce

    Not so much a question but I’m just curious. When implementing the color option for example. I’ll typically end up having a separate file, eg. styles.php, which will house a function that includes all my CSS rules that use that color option, and then add it through wp_head.

    Is there a better/preferred way of including such css rules that are defined by options?

  33. kraymer

    Hey Devin,

    Your framework is really awesome! I can’t wait to start hacking away at it.

    My only two wishlist items (and one, you already addressed) are image/content sliders and shortcodes. I saw, shotcodes aren’t enabled, but are there any plans to add this functionality?

    Image/Content sliders would be pretty cool for home pages and gallery or portfolio pages.

    Either way, just wanted to say great work and thanks for making this available at such a reasonable price!

    ~kraymer

      1. Hi there,
        i’m wondering how this is possible as well. Ive tried adding the php to an editor options panel, however I don’t think it will echo on the front end.

        I’m assuming because WordPress doesn’t allow php to be placed into editor’s. Would love more information, or a workaround on this.

        Thank you!

  34. Deryck

    Hi there,

    Everything is working fine! Well, almost everything. If I use ‘editor’ the input output empty. No editor, no textarea, anything. ¿Any suggestion please?


    $options[] = array( "name" => __('Test editor',THEMENAME),
    "desc" => __('Testing editor',THEMENAME),
    "id" => "tyni_mce_field",
    "std" => __('Smaple text...', THEMENAME),
    "type" => "editor");

Leave a Reply