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

    Hi there,

    very good option framework. thank you for sharing.

    got some question regarding to background position option, for No Repeat option currently it’s set to be “none” which is not on background css property, so I have change to be no-repeat instead.

    correct me if I am wrong I was try to make a css shorthand for background property

  2. Marko

    Hello,

    I need uploader to upload files (in my case only .js files) to custom directory. Would that be hard to edit in code? I just can’t find what to change. Is that in theme-options.php (starting from line 58 — $uploads_arr…), and is there a way to put absolute path to folder where I’d like to upload files.

    In fact, I need only one uploader to upload files to one directory, so I guess I’d have to make double function in order to make it work.

    By the way, this is great thing to learn WordPress back end. Thanks.

      1. onioneye

        You’re welcome! :) I’m just glad I get to use your awesome framework for my projects.

        BTW, I have one question. In the newest version, I can get the of_get_option function to work in the main functions.php file. I used to keep my functions in the theme-functions.php file, but that’s gone now, and I’m not quite sure where to put the functions that I still need to be used.

      3. onioneye

        I know about that function, and I regularly use it to include files into a php script, but that’s not what I’m looking for. The thing is, I’m enqueueing jQuery scripts based on some of the options in the options panel, and I can’t get the of_get_option to work in the function.php file. I tried including the options-framework.php in the functions script, and it’s working alright, but out of some unfamiliar reason, when I do that, my theme options in the WP admin panel get messed up.

        Here’s a screenshot, so you can see how it looks, when I do that: http://awesomescreenshot.com/00ddebwda

      4. Devin

        The stylesheet should load fine. I’d remove the customizations you made and make sure that you’re using the javascript hook I included to load additional scripts (e.g.) add_action(‘optionsframework_custom_scripts’, ‘optionsframework_custom_scripts’). You should download the plugin version from GitHub and view the Options Check theme if you want to see a full example.

  4. Guido

    hi nice to see that you update the option framework. i used the version 0.2 and updated it in my theme. In your predefined advanced settings there is an “Check to Show a Hidden Text Input” but it doesn’t work.

    so, do you have any solutions for that or is it an implementation mistake for my part?

    Thanks for your work.

      1. Travis

        Devin,
        This is a great tool, you are a saint to give it to us. I am noticing the same concern as Guido. I read that you closed the ticket, but I believe that I am using the most recent version. (v0.3).

        What did you do when you closed the ticket? Maybe I just need to replicate your actions… Thank you so much!

  5. henri

    Hi Devin,

    I want to add your option framework to my free theme for the codex and I have a couple of remark about this and I want to share this to you :

    -Themes are recommended to use Settings API for its theme options.
    -Do not query wp_options table directly. use (get|update|add|delete)_option functions,
    $query = "DELETE FROM $wpdb->options WHERE option_name LIKE '$id'";
    $wpdb->query($query);

    $query = "DELETE FROM $wpdb->options WHERE $query_inner";
    $wpdb->query($query);
    -Themes are required to save options in a single array, rather than create multiple options for its settings page
    -For checkboxes and select options, Themes are required to use the checked() and selected() functions for outputting checked="checked" and selected="selected", respectively.
    -Themes are required to validate and sanitize all untrusted data before entering data into the database, and to escape all untrusted data before being output in the Settings form fields or in the Theme template files (see: Data Validation)
    -Themes are required to use esc_attr() for text inputs and esc_html() or esc_textarea() for textareas.
    -Themes are required to provide explicit Settings-page nonce checking, if not using the Settings API (see: WordPress Nonces)

    Thanks for your inputs about this!

  8. WOOW.web.ID

    I use Option Framework in my wordpress plugin project, and also use it in my wordpress theme project. then I activate my plugin ( wordpress still use the default theme ), and there no conflict, the plugin option page work well, then I activate my theme that use Option Framework too, for the theme option panel and the problem occur. The wordpress theme option panel appear in admin dashboard but not work in the theme frontend…is there any solution to fix that problem?

      1. WOOW.web.ID

        Problem Solved, I used this code :


        <?php
        $category = of_get_option('mainheadline');
        $showpost = 1;
        $headline = new WP_Query( 'cat='.$category.'&showposts='.$showpost.'' );
        while ($headline->have_posts()) : $headline->the_post();
        ?>

        GREAT Option Framework, Thanks..!

    2. AJ

      Oh man, I am glad I did a page search because I ran into a problem trying to create a custom home page that displays 3 posts in 3 columns by using a category selection from the settings: of_get_option(‘home_blog_category’); and it wasn’t changing the category when I was testing it. My code was this (hopefully this comment doesn’t strip out the code) originally:
      3,
      'category_name' => $homeblogcat
      );
      $my_query = new WP_Query($args);
      ?>
      Anyway, I used the other method posted in your comment except I put the have_posts in another part. Long story short, this one worked for me after 2 hours trying to figure out why my category wasn’t changing. Plus, if I added the “of” from of_get_option, my blog posts would disappear but show up if I took the “of” out. Time for a coffee and cross my fingers this keeps working.

      1. AJ

        damn… it stripped my code out. How did you show your complete php code? I used the code tag in the comment editor here and it obviously didn’t work?

  9. B1fr0st

    Thanks for this awesome piece of work!

    Although your options framework theme is (I think) the best available I’m missing the possibility to select a default image within the upload field.

    Greetings
    B1fr0st

  10. Marco

    Hi David, Good job!!! congratulations! I want to know how i can implement your framework to use with my theme..

    Thanks a lot for answer…

    marco

      1. Marco

        Thanks Devin, but i want to know how i can implement in another folder like ” functions ” on my base theme.

        i’v pasted functions.php code (framework) in my functions.php (theme) and not works fine, give me blank page, have you any ideas? Thanks so much Devin..

  11. Marco

    Hi Devin, i’v included in my theme but i have problem savings data, why ? don’t save and restore default data.. you have any ideas?

    Thanks

    MArco

      1. Devin

        Make sure optionsframework_option_name is in your options.php file and it is actually setting a name to save the option with. No spaces weird characters, etc.

  12. Erik Ford

    I ask this question, via Twitter, but probably should put it here since it may benefit others. We’ve just finished developing a theme using your framework as our Theme Options. One of the things we advocate strongly to users is child theming for customizations, whether large or small.

    I noticed, when activating a child theme, there is an error that no such directory exists. After looking at your code, I see you have a condition for if the framework is installed in either a parent or child theme, if I am reading that correctly. Since, in our case, the framework will always exists in the parent, I removed the condition and the Theme Options loads just fine. But, I see that any of my settings from the parent theme do no appear and the defaults are loaded. Is that intentional?

    1. Devin

      That is intentional, but you can always set $optionsframework_settings[‘id’] in function “optionsframework_option_name” of options.php to override. If you release multiple themes you could even have it use the same settings id for all.

  13. onioneye

    Hi there!

    I just wanted to let you know that if you set a default image in the upload field, the link to it can be deleted only if the image is overwritten with another one; otherwise, the value of the upload field will always return a link to the default image.

    Cheers! :)

  14. Yasir Arafat

    Hello Devin,
    Thanks for the usefull framework. Its really a good job. I am using a your framework. I need your help regarding multiple selection from dropdown. How can i do that. (I dont know which version i am using. ). I am trying to use the following code but nothing showing except title and description.
    $options[] = array( “name” => “Multiple selection box”,
    “desc” => “This is a descriptions”,
    “id” => $shortname.”_multi_select_dropdown_menu”,
    “type” => “multiselect”,
    “std” => “Default”,
    “options” => array(“Defaults”, “Option 1s”, “Option 2s”));

    Thanks
    Arafat

      1. P Nut

        Maybe I could ask for that feature in a future release if you don’t mind? it will be a very helpful feature especially for theme owners who wish to use same settings or are moving their theme :)

        Thanks for your time. :)

  16. Alex

    Hi Devin! I was looking at this tut: http://www.sitepoint.com/wordpress-options-panel/ and I have a question, I’m just a designer, What’s your opinion about doing the theme option your way and doing it using the Settings API? For me becomes easier using the API because there many things built in. I’m not an expert of anything I just want to know which way to choose when building one. Very nice your framework! Thanks.

      1. Alex

        Got it! Yes, I was a little confused because I’ve seen about three different ways of doing it.

        Then the add_settings_field (); is the equivalent of $options[] = array(); ? Right?

  17. Jinson Abraham

    I was checking this theme. I tried to enter the youtube embed code ( iframe code) in the text area.
    But it returned nothing on the page. Just came back as “no entry” . Is html not allowed in the text editor?

  18. adam

    I have setup the options frame work but the uploaded isnt working. It saves the image to the wordpress media collection but it does not appear on the theme options page after i hit save. I hit save and the image disapears. Any idea on how to begin trouble shooting this problem ? Thanks in advance and great plugin!

    -Adam

  19. Alex

    Hey Devin, Yes, the image disappear after saved, I guess that’s the way it is. I want to include a Nivo slider in the option page, so my question is what do I have to do to show the image of every slide after upload.

    I found this article about including Nivo as an option: http://zeaks.org/twenty-ten-slider-theme/ but is pulling images from a category. So, I want to expand it uploading images from the option page.

  20. dan

    i too would love to know this alex,ive seen themeforest themes like dynamix and awake who have “slidesets” in the options,so you have image src url,title,description,and any atributes required for the slider like open in lightbox or custom url,apply reflection,tween types for flash sliders and video url etc, all in a slide,then a button can be selected to add another slide.each slide has a user input textbox for a slideset id so it can be called into a slider,an image/video shortcode etc,possibilities are endless.

    I would kill for a tutorial for this.

    1. Alex

      Man I’m just a designer. I’ve learn a lot about php trying do my own option page but, one thing is to put a logo or a google analytics, etc. and a whole different game is put in your options page a Nivo slider, I’m not at that level yet, jaja. I’m just gathering info as much as I can and trying to learn the drill.

      I don’t know of a tutorial like that, it would be nice. I want to sell templates on themeforest but I’m gonna need the option page to do it.

      1. dan

        thanks,but that plugin isnt much good for devs of premiums themes for themeforest etc,licensing etc etc.

        :(

        i use wp alchemy for my page metaboxes and you can create repeating fields,is this possible in options framework?

      1. dan

        thanks,spotted that a while ago but a little basic but on the right path for sure,id like to see that code but with the ability to have several slide SETS,his code i believe is for creating several single slides which is great but id like to enhance that further to several slides in a set with several sets,so the sets can be called into a slider,portfolio page,widgets etc.i know this is possible using tables as andy @ creative workz has applied this to his dynamix theme on themeforest.

  21. Evan

    I used your option framework v0.3 on my wp theme, tanks for the great framework. I have problem when I use textarea to insert google analytics tracking code or HTML tags. I insert my track code: //track code then when I press save options button and disappear and my code become //track code, can you or anyone help me? thanks

  22. Paul

    Hi! is there any way to dynamically add fields? I need to include a “testimonials” option in my backend, and for that I need to give the client the option to add X number of testimonials. Does anyone know if this is possible with the current version?

    thanks!

    1. Devin

      You can’t create new options dynamically. You could include hidden options with a limit of 10 or so. But I think this functionality is probably better handled through custom post types since it is a form of content.

  23. Casey

    Hi, Is it currently possible to override ‘of_recognized_font_faces’ in the theme version of the framework? I suppose I could edit options-sanitize.php manually, but not sure this is the best way?

    2. Devin

      Oh wait, didn’t realize you posted this for the theme version. You can override it however you like. I’d probably edit it directly myself, but its up to you.

      1. Nim

        Hi Devin,

        I just updated with new version & i can no longer see the left side tabs. tabs are appearing in top (horizontal). is it correct behavior? or am I doing something wrong??

  27. Mayur Jobanputra

    Hey thanks so much for making this framework. It’s really easy to use and I was able to code/implement and skin within a day a home page slider for my client.

    Problem/Question: I want to use html in the textarea field. How can I do that? Everytime I save, it clears the html code.

  28. Brenden Clerget

    Hey Devin,

    Great framework, just struggling with something, maybe I’m missing something.

    I changed the add_submenu_page function to add_menu_page and changed the parameters and it’s adding my theme options as it’s own options page now (which is what I want) but none of the uploaders nor the “Hidden” classes work.

    Any ideas?

    – Brenden

    1. Devin

      Yes, certain javascripts and get loaded based on the options page url. You’ll need to make sure those paths are correct in options-medialibrary-uploader.php.

  29. AJ

    So far this is still a fantastic cpanel for a theme…however, I noticed when I was doing a single checkbox to enable or disable a div container, it wasn’t working. So I went in to see what and why, and then I noticed something…now for the record, I’m no php programmer and would take me a couple years to do what you have done, but in my past themes I’ve made with control panels, the checkbox option in your framework has this:
    "std" => "1", but from what I understand, it should be this:
    "std" => false, So basically not a digit but should be either a true or false without the quotes. Am I correct on this assumption?

    I edited the option be false, and now I can enable or disable my div container in the theme page.

      1. AJ

        ok, very weird, I changed it back to the 1 and now it works. Thanks for the link to the checkboxes and booleans. Now I just have to try and figure out how to get 3 most recent posts on a “page’ from a category select option…I’m trying this from someone elses theme that is based on your framework but it appears this:

        3,
        'category_name' => $homeblogcat
        );
        $my_query = new WP_Query($args);
        ?>

        …is what does it. Unfortunately it’s not working for me. You might want to consider this for a future tutorial on your site :)

      2. AJ

        lol… forget about the part of my last post with the code I tried to paste in…part of it was stripped out when I clicked submit.

  30. Nim

    Hi Devin,
    is there any way to make selection box to work similar to advanced checkbox,
    show/hide more items depend on selected option?

    for example, I have 3 different sliders to select in theme options panel. when i select slider 1 from selection box, I need to show slider setting options for slider 1 & so for slider 2 & slider 3

    I tried with following code, but its not working from me.
    in functions.php

    jQuery(document).ready(function() {
    jQuery('#hero_style').change(function() {
    jQuery('div.number').hide();
    jQuery('#section-' + $(this).val()).show();
    }).change(); // Invoke it now
    });

    in options.php


    $options[] = array( "name" => "Slider Style",
    "desc" => "Select slider style from the dropdown list",
    "id" => "hero_style",
    "std" => "yellow",
    "type" => "select",
    "options" => $hero_styles);

    $options[] = array(
    "desc" => "slider option for cycle slider",
    "id" => "cycle",
    "std" => " ",
    "type" => "text");

    $options[] = array(
    "desc" => "slider option for cycle slider 2",
    "id" => "cycle2",
    "std" => " ",
    "type" => "text");

    1. Devin

      I don’t really have time to build out the script and test, but a quick look makes me think you want to use jquery(this) rather than $(this).

  31. AJ

    Using a textarea for adding Google Analytics as one other posted earlier is having it’s opening and ending javascript tags stripped out once clicking Save. I read the posts about html being stripped out with a solution to change the $allowedtags with $allowedposttags in lines 10 and 11 of the options-sanitize.php file, but this didn’t prevent the stripping of the tags…is there an alternate solution so google analytics can be pasted into a textarea? Thanks in advance.

  32. Jorge Martinez

    Hi I am trying to do the following in this amazing option that you did this is the next thing I do is slide but I put the code works if you give me a hand thank you very much a serious question I have is what is the shortname of options.

    1. Devin

      You shouldn’t need to use the shortname in the latest version of this project. That was previously used to prefix the option in the database, but now it simply uses the theme name and stores all the options in a single array.

    2. Jorge Martinez

      you can offer your help I am not scheduled and I’m Designer makes it very difficult?

      is so remote as to call my option:

      $slide = get_option(‘example_select_categories’);

  33. Paul

    I am working on icorporating the functionality of adding fields on the fly to the framework. I find this useful in cases where you need to let users add X lines of contents. Lets say, create sidebars on the fly, etc.

    I am able to add/remove inputs on the fly, but I am having serious problems when it comes to saving the data.

    So, if there is anyone who is in the same issue than me and wants to work together on this issue please drop me a line so we can try to figure this out.

    Thanks!

    1. Devin

      The Options Framework wasn’t designed to create options on the fly. You might want to check out Option Tree (http://wordpress.org/extend/plugins/option-tree/) which does load options from the database rather than a file. Or, specifically for sidebars, check out what WooThemes has done: http://www.woothemes.com/2010/09/sidebar-manager-now-your-sharpest-tool-in-the-shed/.

      For creating multiple pieces of content (titles, testimonials, slides, quotes, etc), I’d suggest using a custom post type rather than an options panel.

  34. Brett

    I noticed something strange. Typically, you can click the label to activate a check box, but this is not the case in the framework. The radio buttons work as expected though.

    Thanks for the super helpful tool!

  35. AJ

    This is kind of an emergency….I just finished making a WP theme using this options framework and up until a couple hours ago, all is well. Then I realized I had to change the theme folder’s name because the name Purity is already used by someone else. In Dreamweaver you can do global find and replace which I did and also updated the linking (which I should not have done). Now, either it’s just coincidence or not, my theme went haywire and so I decided, ok, I will simply do a clean install of WordPress 3.2.1 and use a previous zip backup of my theme (with the options framwork) which I know works. However, now all of a sudden, the options in the theme settings panel (and tabs) are collapsed. The options are there in the source code, but the panels have completely collapsed. So then I tried an older backup I had, it’s still doing this with a fresh WP install, computer restore, previous backups of the theme…still not working. The site functions still….so I tried what I thought was a fail safe test by using your plugin version…nope, the options (even with the default setup) does the same thing. So…..any idea what is causing the options in each tab of the theme settings to collapse, but still show in the source code and the website front-end works? A Screenshot.

    1. AJ

      a quick follow up…something about my computer has changed and causing the options to collapse all of a sudden. I disabled plugins to see if it was that, but still happens. Then I decided to install WP on my live server and installed the theme….all is working fine. So, now I have to find out what it is on my computer that has recently affected this functionality of the option settings beeing seen. Long story short, it doesn’t appear to be the framework or even the name change I did for the theme…I think.

  36. Evaldas

    I’ve noticed one thing, don’t know actually if thats a bug or it’s meant to be that way.

    My option id looks like this "id" => "logo-url". As you can see I’m using a dash(-). When it saves an option to the database it drops the dash. And when I’m trying to retrieve the option echo of_get_option('logo-url');, it doesn’t retrieve anything. So when retrieving an option I also have to drop the dash from the option name. Using dashes in ids or classes is my old habit and also official WP documentation recommends this way.

    I’ve tried using an underscore(_) in my ids and it worked perfectly as in the example theme.

    1. Evaldas

      By the way I’ve just noticed that when the options are reset to default values, the database stores their names with the dashes and when I hit “save”, they are stored without dashes.

  37. hoko

    Hi,

    First of thanks for your great plugin / code / effort.

    When I update it from version 0.6 to 0.8, I see that there are a couple user interface improvements in 0.8 which use wordpress default admin tabs. May I ask what can we do if we have more than 10-15 headings with those new wordpress tabs? Don’t you think that previous version of heading on the left column(vertically) is much more better than this new one at the top (horizontally) with width limitation?

    Thanks…..

    1. Devin

      The changes were designed to make the plugin more consistent with the WordPress UI. I have considered making it so you can have both tabs and metaboxes, which would allow more flexibility. But another route would be to trim the amount of options available. :)

  38. hoko

    Is there any possibility to go back with older version instead of new tabs ? I searched for version 0,6 files but I couldn’t find… Thanks….

  39. Adrian

    Thank you for making this, I’ve been messing around trying to change the way it saves the data, I’m trying to use the built in jQuery ajax .post method but have had no luck, any advice?

    1. Devin

      No plans at this time- it’s not something I’d really like to support. But I will be trying to make the plugin more extensible though, so folks could conceivably add that as a new option if they choose.

  41. iCosmin

    Hello Devin,

    Just wanted to add something to the OF, in terms of usability.

    As it is now, for checkboxes, you have a div with the class “explain”. I really think that should be a label instead.

    So, on line 306 of options-interface.php, it should be:

    $output .= '' . wp_kses( $explain_value, $allowedtags) . ''."\n";

    Hoping to see this implemented in the next update :)

    Best,
    Cosmin.

    1. Devin

      Yes! Very cool. I’m hoping to check out your theme in more detail when I have some time, especially since I’m building out bbPress templates for the theme I’m currently using.

      1. Simple Themes

        Cool. I’m going to branch the bbPress version just to keep it clean for folks who don’t need it. I’ve also just pushed a jigoshop branch (alpha) if you need it.

  43. mpc

    Hi, I really love your panel, I would like to customize it to my needs, on the screen shot I see that you have buttons on the left, when I added the OP to my project I see only tabs is there a way to display both, buttons on the side and tabs? If not could you push me in the right direction, how to make this change?

    1. Devin

      The theme was built just to display one theme option page. You can use tabs to display different sections, but it would take some customization if you wanted to display different option pages.

  49. Cristian

    Hi Devin, great job!
    If I can suggest something, theme options should be exported and imported. This would improve theme portability through different WP installations (as develop environment, test and production).

    1. Devin

      I have no plans to build that directly into the plugin, however, a more generic plugin that allows you to export/import any setting in the database might be useful.

      1. P Nut

        I tried copy/pasting your code into my functions.php but it says Parse error: syntax error, unexpected $end in /*******/functions.php on line 638

  50. dCartes

    I’ve tried implementing “remove the default santization” code from here, but failed. Can you help me for a while?

    My goal is simple, how to put a “script” tag in the textarea without being strips out. You tell how to do it, here, again I failed. Do I have to manually create an array $ allowedtags or $ allowedposttags? Since I do not find them declared everywhere.

    I appreciate if you tell me how to overcome my goal. Thank you.

    1. Devin

      When you copy/paste the code underneath “Allow Script and Embed Tags” it should work (or did last time I checked). When you put “global” in front of $allowedtags, it uses an array WordPress generated. $custom_allowedtags is declared in the code directly underneath.

Leave a Reply