Ready to get started?Download WordPress

Theme Review Team

Tagged: Settings API Toggle Comment Threads | Keyboard Shortcuts

  • Chip Bennett 1:22 am on July 9, 2014 Permalink | Log in to leave a Comment
    Tags: , sane defaults, Settings API, Theme Mods API   

    Using Sane Defaults in Themes 

    With the release of WordPress 3.9, one of the changes to the Theme Review Guidelines is that Themes must use sane defaults. That means that Themes must not write default setting values to the database. For many Themes, this may seem like a major change; but it doesn’t have to be. This post will step through a few ways to implement sane defaults.


    To make this method easier, put all of your defaults inside a function:

    function themeslug_get_option_defaults() {
    	$defaults = array(
    		'option_1' => 'value_1',
    		'option_2' => 'value_2',
    		'option_3' => 'value_3'
    	return apply_filters( 'themeslug_option_defaults', $defaults );

    (Note: by making the return valuable filterable, the Theme defaults can be easily overridden by a Child Theme or Plugin.)

    We’ll make use of this function later.

    Options API

    Most Themes use the Options API, and will use get_option() to put Theme settings into a global:

    $themeslug_options = get_option( 'theme_themeslug_options' );

    Knowing that this get_option() caall will return FALSE if the option has not yet been saved to the database, Theme developers have taken to saving default values to the database as part of Theme initialization, like so:

    if ( false == get_option( 'theme_themeslug_options' ) ) {
    	update_option( 'theme_themeslug_options', themeslug_get_option_defaults() );
    $themeslug_options = get_option( 'theme_themeslug_options' );

    But this is entirely unnecessary. And everything needed to implement a better solution already exists.

    As a first step, consider that get_option() includes a second parameter, which specifies the default value to return, if nothing is returned from the database:

    get_option( $name, $default );

    So, the simplest solution is merely to tell get_option() to return the defaults, using the function we previously defined:

    $themeslug_options = get_option( 'theme_themeslug_options', themeslug_get_option_defaults() );

    This works, but isn’t perfect. It will return the Theme-defined defaults if the user hasn’t saved settings to the databse. But if later versions of the Theme add, remove, or change options, this might break, since the return value is either/or: either the database-saved setting, or else the defaults. So, if the user saves settings, and then a new setting is added in a later Theme version, the new setting value won’t be included in $themeslug_options unless/until the user saves settings again.

    The solution is to merge the arrays, rather than to return one or the other. WordPress has a core function specifically for this purpose: wp_parse_args(), which will use the settings array, and “fill in the blanks” with the defaults array:

    wp_parse_args( $settings, $defaults );

    Caveat: bearing in mind that wp_parse_args() expects both parameters to be arrays, and knowing that get_option() returns FALSE by default, be sure to specify get_option() returns an empty array by default: get_option( ‘theme_themeslug_options’, array() ); otherwise, wp_parse_args() will (might – see note below) choke if the user hasn’t saved settings to the database.

    The construct will look something like this:

    $themeslug_options = wp_parse_args( 
        get_option( 'theme_themeslug_options', array() ), 

    This is perhaps the simplest, most elegant way to implement sane defaults.

    (Note: according to Otto, passing an empty arrayy() as the second parameter to get_option() isn’t necessary. In his words: “The wp_parse_args() function checks for the first parameter to be an object or an array. If it’s neither, then it calls wp_parse_str on it, because it can take a GET URL-like array of parameters too. The wp_parse_str() function calls PHP’s parse_str on it, and does a deep strip_slashes if magic quotes is on, then filters the result. So, because false maps to the empty string, parse_str will return an empty array for it, so passing false to wp_parse_args should be A-OK and probably has been like that for a very long time. Doesn’t hurt to add the empty array(), but doesn’t really change anything.” YMMV.)

    Theme Modification API

    Using the Theme Modification API (get_theme_mod()/get_theme_mods()) is fairly similar.

    An individual setting can be called via:

    get_theme_mod( $name, $default );

    But perhaps more useful, all settings can be called via:

    $themeslug_options = get_theme_mods();

    Since get_theme_mods() returns an array, you can use the same technique as with Options API settings:

    $themeslug_options = wp_parse_args( 

    Portability/DRY (Part 2)

    To be able to use this method throughout the Theme, wrap the wp_parse_args() call inside a function:

    function themeslug_get_options() {
        // Options API
        return wp_parse_args( 
            get_option( 'theme_themeslug_options', array() ), 
        // Theme Mods API:
        return wp_parse_args( 

    Then, wherever you need access to Theme options:

    $themeslug_options = themeslug_get_options();

    From there, you can globalize $themeslug_options, or cache/transient it, etc. When you need to add a new option, simply add the new option default to the defaults array, and the Theme will handle it automatically.

    • Justin Tadlock 2:05 am on July 9, 2014 Permalink | Log in to Reply

      No need for the custom filter hook there on the defaults. Child theme authors can simply filter 'default_option_' . $option if they need to overwrite this.

      • Chip Bennett 12:32 pm on July 9, 2014 Permalink | Log in to Reply

        But that only works if the option is not yet set in the database, right? In which case, it’s a bit more fragile, and wouldn’t work in the case of a Theme (or Child Theme) adding a new option in a later version of the Theme.

  • Chip Bennett 2:43 pm on July 1, 2011 Permalink
    Tags: , , Settings API   

    WordPress 3.2: Fixing the edit_theme_options/manage_options bug 

    Theme Developers:

    Many of you are aware of a minor bug in the Settings API implementation for Themes, in which add_theme_page() is passed the “edit_theme_options” capability, but the settings form submission via options.php requires the “manage_options” capability, resulting in users with the Editor role having access to the settings page, but being unable to submit the settings page form.

    Fortunately, WordPress 3.2 adds a new filter that can be used to resolve this issue: option_page_capability_{option_page}, where {option_page} is the name of the option page, as defined in the fourth parameter passed to add_theme_page().

    To get an idea of how to implement the fix, refer to the patch for the filter, which also includes an implemented fix for TwentyEleven. The key is to ensure that the capability passed to the hook is the same as the capability passed to add_theme_page.

    Here’s one example of how to implement:

    First, create a function to return the “edit_theme_options”:

    function themeslug_get_options_page_cap() {
        return 'edit_theme_options';

    Then, hook the function:

    add_filter( 'option_page_capability_themeslug-options', 'themeslug_get_options_page_cap' );

    Then, ensure consistency with the add_theme_page() call. Notice that I replace the hard-coded string with the previously defined function:

        'Theme Name Options',
        'Theme Name Options',

    If you’re already testing against the 3.2 Release Candidate (and you are, aren’t you?), you should now be able to save Theme settings as a user with the Editor role.

    • Carl 9:44 am on October 27, 2011 Permalink

      The variable {option_page} in the filter option_page_capability_{option_page} should not be the fourth parameter from the add_theme_page call.

      Rather, it must be the same as the intended settings group that is to be modified. Clarification: the first parameter when doing register_setting(‘settings-group’, ‘setting’);

      For many these are set alike but that might not always be the case.

  • Chip Bennett 7:50 pm on January 5, 2011 Permalink
    Tags: Settings API,   

    Themes and the WP Settings API 

    The Settings API was initially introduced in WordPress 2.7, and is incredibly powerful. Part of its power is its automation of settings security (nonces, etc.), as well as automation of most of the admin options-page generation. Thus, use of the Settings API helps ensure more robust data security and more consistent user experience.

    Unfortunately, it doesn’t seem to have met with much widespread adoption in Theme development. Granted, very little documentation exists for proper implementation of the Settings API, and thus the learning curve is somewhat steep. To that end, Otto has an excellent tutorial, and Press Coders have a great write-up as well.

    I will be adding a Theme-centric Settings API tutorial to my to-do list. Given the increasing exposure to WordPress security issues – both real and perceived – I believe that, as we go forward, ensuring the robustness of data integrity and security of repository-hosted Themes will become increasingly important. Further, I believe that adoption of the Settings API will eventually prove to be requirement toward those ends.

    So, Theme Developers: have you tried to use the Settings API? What issues have you encountered? What difficulties do you envision in attempting to migrate your Themes’ current settings functionality to use of the Settings API? How long do you believe would be reasonable before the Theme Repository begins encouraging Theme developers to use the Settings API, either as a recommendation or as a requirement?

    Please note: this is an extremely early-stage discussion. At best, use of the Settings API might show up as recommended when the Guidelines are revised for WordPress 3.2. But, we want as much input as possible, as early as possible, so that we can begin addressing whatever concerns may exist.

    So, what are your thoughts?

    • Frumph 8:02 pm on January 5, 2011 Permalink

      Even though I do not currently use the settings API, purely for lack of knowledge of ‘how to’ implement with my already working and usable system with nonce’s and the like, that if it becomes a requirement that I would have to spend a countless amount of hours redoing quite a robust system of options.

      That doesn’t mean that I’m not in favor of moving everything to internal core coding. I am only considering the time involved for the infrastructure change. While it still being a huge undertaking I would rather go with it with complete knowledge on how to implement utilizing a like method with the tabbing and updating of separate options instead of every option, then how to utilize that information after the fact, while those tutorials are decent they are not all encompassing and I believe more work needs to be done with education on their part.

      • Chip Bennett 8:12 pm on January 5, 2011 Permalink

        Absolutely, Phil! Having stumbled through the process once on my own, I fully appreciate the difficulty of the learning curve.

        I want to start with a basic, start-to-finish, Theme-specific tutorial for implementing the Settings API, and then see what kinds of questions remain. Once developers get comfortable with the basics of implementation, then we can move on to advanced topics like the ones you bring up (and that I’m sure others will bring up, also).

        I envision this process taking a considerable amount of time – which is why I want to begin as early as possible, before even thinking about considering adding the Settings API to the guidelines in any fashion whatsoever.

      • Otto 8:55 pm on January 6, 2011 Permalink

        I wouldn’t say to make it “required” anytime soon, but implementing options pages (in themes or in plugins) is fraught with hard-to-spot security hazards that the Settings API makes a whole lot easier to cope with. So I’d say it’s one of those things that is best accomplished through proper tutorials and encouragement.

        “Recommended” is a definite though.

    • Edward Caissie 8:28 pm on January 5, 2011 Permalink

      I agree with the potential for the Settings API to become a recommended item in the Theme Review guidelines with the release of WordPress 3.2; but, a great deal of discussion must take place before it even reaches a point of being truly considered for that milestone. This is a great place to start.

    • Justin Tadlock 9:19 pm on January 5, 2011 Permalink

      I’ve already got half a tutorial written on using the Settings API, which is geared specifically toward theme developers.

      I see no issue in not using it if a theme developer uses the correct capability checks (edit_theme_options), uses nonces, properly validates/sanitizes the data, and escapes it on output within form elements. The Settings API actually makes much of this easier and definitely makes it cleaner.

      There’s also the *_theme_mod() functions a theme may use.

      Some complaints I hear from theme devs is that they can’t do tabs or other fancy stuff with the Settings API, which is entirely untrue. Of course, I’m asked how to do it. My reply is always that they should learn the basics before trying to add more complex functionality. I take the learn to crawl before you walk approach here.

      Our biggest concern should be about security. This comes down to a few things:

      Data validation.
      Proper capability checks when adding theme options pages. I’m involved in a few sites where a theme not using edit_theme_options would open up a settings screen to users that shouldn’t have permission to theme options at all.
      Properly escaping data on output using the esc_*() functions WordPress provides. An errant piece of HTML can break a theme settings page entirely and even be used for more malicious things if the data wasn’t validated before saving.

      The use of the Settings API should be recommended but not required. The requirement should be that a theme take proper steps to make sure there are no security issues. This should also be accompanied by relevant links to data validation and any other related links in the Codex.

      • Chip Bennett 9:41 pm on January 5, 2011 Permalink

        I’m of several minds here…

        On one hand, the primary concern at this point is encouraging adoption of the Settings API by Theme Developers, which will require massive amounts of education.

        On another hand, the Guidelines also say that if functionality is included, it must implement/support core functionality . Couldn’t that requirement be extrapolated to include Theme settings and data validation? If so, then we’re right back to use of the Settings API.

        And on yet another hand, I see no reason not to hold repository-hosted Themes to a higher standard with respect to the Settings API. Sure, Theme Devs can accomplish all the same things by hard-coding everything encompassed by the API; but if we want to remake the reputation of the Theme Repository, it would be in everyone’s best interest to move repository-hosted Themes to standardize on use of the Settings API.

        Not to worry, though; if use of the Settings API appears in the guidelines, it will remain only as suggested for a VERY long time.

        • Justin Tadlock 10:41 pm on January 5, 2011 Permalink

          There are several ways to implement/support core functionality: Use the regualar *_option() functions, use the *_theme_mod() functions, or use the Settings API.

          I’m all for setting a standard with using the Settings API and sticking with it though. I like the idea of eventually strongly recommending the use of the Settings API. Over time, we could check themes not using it on a case-by-case basis.

          I’d rather see something up on the theme review guidelines sooner rather than later though, even if just a small addition of text that theme settings pages will be checked for security issues and a link to the Settings API page in the Codex.

          Whether adopting the Settings API or not, this is an area that will require massive amounts of education. Nearly every theme I’ve looked at with a theme settings page has major issues. Most theme developers simply don’t know the first thing about properly creating a settings page. They’re using some generic script they’ve copied from a blog or another theme that just doesn’t cut it. One of the reasons I haven’t finished my tutorial yet is because there’s so much ground to cover and to put into a single tutorial.

          I’m also volunteering myself to check any theme settings pages for other reviewers that aren’t familiar with it enough. So, anyone can feel free to shoot me an email if they want me to look this over.

          • Chip Bennett 10:50 pm on January 5, 2011 Permalink

            I think we’re on the same page. Education is key (and I’ve got just about as much to learn as everyone else), and is what I think needs to be our primary focus for the foreseeable future.

            As for the current guidelines: any improvements you can make to the wording of the section regarding security, please feel free! We need to ensure that we at least have a link to the Settings API Codex page, if nothing else.

          • Edward Caissie 12:59 am on January 6, 2011 Permalink

            I’m all for this:

            I’d rather see something up on the theme review guidelines sooner rather than later though, even if just a small addition of text that theme settings pages will be checked for security issues and a link to the Settings API page in the Codex.

            Feel free to add some draft text at the appropriate places (here and the Codex).

    • Andrew Nacin 3:44 am on January 6, 2011 Permalink

      I’m strongly for the Settings API here. I’m also for a single option per theme, saved as an array and properly sanitized with a sanitization callback. I’m for edit_theme_options, despite the Settings API only supporting manage_options currently. I’m for secure themes. I’m for education.

      That said, there are areas where we can improve on this on core. Here’s a quick list I can refer to later: I already mentioned edit_theme_options/manage_options. Justin mentioned the theme_mods API, which would be powerful when combined with the Settings API. An array of options should be easier to do in the Settings API, perhaps. Themes need activation, deactivation, and uninstall hooks.

      Let’s see how much of that we’ll be able to do in 3.2. If you’re aiming for 3.2 as a guideline, that gives us some time to make the API more mature for theme pages. We also plan to re-do the settings screens in 3.2 (possibly), so this (possibly) is a good time to move forward.

      • Edward Caissie 8:14 pm on January 6, 2011 Permalink

        WP 3.2 is the ideal implementation of this addition to the guidelines and why we wanted to start this and other discussions now.

      • Ken Newman 10:11 pm on March 28, 2011 Permalink


    • Devin Price 6:17 am on January 6, 2011 Permalink

      The work Ptah Dunbar has done in WP-Framework beta is really impressive. With three lines of code you can set up an options panel and an option:

      add_theme_support( ‘theme-options’ );
      wpf_register_metabox( ‘options’, ‘general’, __( ‘General Settings’, t() ) );
      wpf_register_option( ‘general’, ‘textbox’, array( ‘type’ => ‘textbox’, ‘label’ => __( ‘This is a sample textbox’, t() ) ) );

      I’m sure any theme developer could handle that much. It would be lovely if something like that got tried out in plugin territory or eventually brought into core (which would standardize option controls and styles across the board).

      I’m also looking forward to a Tadlock tutorial- that tends to make everything much easier.

    • pross 9:07 pm on January 6, 2011 Permalink

      I’m all for making it ‘Required’ for 3.2 and recommended as soon as possible seeing as there is a flurry of settings API blog posts this last few days.
      I really hope the those activation/deactivation hooks become part of 3.2.

      @Nacin I just converted my theme over and its working fine with edit_theme_options (latest trunk)

    • Bruce Wampler 5:40 pm on January 10, 2011 Permalink

      First, although the concept of a settings API is sound, it certainly was not anything I was aware of when I started my own theme development. For me to ever switch to it now would literally take at least 40 or 50 hours of my time, and would result in no visible improvement for the user interface. If I were ever required to switch, I would be forced to abandon my theme. Thus, my first recommendation is that any future requirement grandfather in existing themes, especially ones that do use nonce for settings.

      Second is the sanitizing. One of the major features of my theme is the ability of the site admin to add real code – CSS, HTML, JavaScript, even PHP – to their site. None of the existing sanitizing functions currently in WP work right when allowing such low level flexibility. So given that a large number of WP users really want to do that, that capability – letting almost anything through – must be taken into consideration when the term “sanitizer” is used. I think a sanitizer with different levels – both of the admin logged on, and code level – might be useful.

      I do find it interesting that the existing text widget available for everyone to use has essentially no filtering on it at all – I assume because so many people uses it to add scripts from various external sites – at least that is how I read the source code for that widget. This does leave me a bit puzzled at all the discussion about sanitizing admin inputs from a theme options panel.

      And finally, a theme admin framework would be great, to be sure. Many themes have just a few, basic options, and being able to implement them in just a few lines of code would be great. On the other hand, some themes (which include many of the currently most popular themes) have hundreds of settings, and likely need total flexibility in designing the admin option interface. That is one thing I certainly would not like to give up. I’ve spent a huge effort producing what I think is a very easy to use interface, and I wouldn’t want to be constrained by a requirement to use some standard framework or interface.

      I agree Andrew’s comment above of a single option per theme (which I interpret to mean a single entry in the database per theme – although one might not be enough – my design likes having 3). But having a database call per setting is just far too inefficient, and difficult to uninstall.

      And finally, while it is important to ensure security, it is also important to allow some free rein on creativity. While some themes are being developed by experienced programmers, many are being developed by hobbyists and graphic designers. It would be shame to lose all that creativity by imposing an overly strict set of requirements for theme development. While it may have been overly free before your group was started, I hope the pendulum doesn’t swing too far back.

      Perhaps there could be a level of certification for themes –
      1. Secure – theme uses WP security API
      2. Likely Secure – theme uses WP security measures
      3. Admin Level Security – only admins can use theme admin panels
      4. Security Unknown – use at your own risk – theme not known to use WP security measures

      or something like that. That would be far more useful than eventually forcing all theme developers to use a specific settings API or framework.

      • Chip Bennett 8:24 pm on January 10, 2011 Permalink


        You bring up great points, and your comment epitomizes the reason that we’re having a very early discussion on the topic before we make any changes.

        I’m curious why your “design likes having 3″ database options arrays? Why not a single, flat array with all options? If necessary, why not an array of 3 arrays?

        While I agree that the issue of complex user data input will need to be handled appropriately, I disagree that implementation of the Settings API in any way stifles creativity – especially for the hobbyist/graphic-designer-developed Themes, who are considerably less likely than developers more intimately involved with WordPress code to have a good grasp on proper data handling for Theme options pages. (Note that, for Themes without any options, the Settings API doesn’t even come into play.)

        While there may be a place for rating/ranking the security measures of each Theme, and while such information may be useful to end users, I see it as representative of considerably more work for the people tasked with reviewing Themes. As for your specific certification levels:

        1) Secure – Theme uses WP (Settings) API: this is where we want all Themes with options to be
        2) Likely Secure – Theme uses WP security measures: I’m not really sure what this means. IMO, “WP security measures” is equivalent to “WP Settings API”.
        3) Admin Level Security – only admins can use Theme admin panels: all Themes with options should meet this standard. The call to the settings page includes a capability argument for good reason.
        4) Security Unknown – once we implement Guidelines regarding data security, I don’t see any Themes that fall into this category passing the review process.

        The biggest concern I’m hearing so far is from Theme Developers who have already developed elaborate Theme settings pages, and are dubious about the feasibility, need, or benefit of switching to use of the Settings API.

        First, our primary focus, at least to start, will be the Themes that don’t properly implement data security in their settings pages (e.g. Themes that use copy-pasta from who-knows-how-many years ago).

        Second, the Settings API does not preclude any particular layout or design of Theme settings pages.

        Third, part of the philosophy of the WordPress project is to have a consistent UI/UX throughout the application. So, I see it as a benefit to end users to ensure that Theme settings page UI is consistent with the rest of WordPress.

        Fourth, our major emphasis, long before any Guidelines changes are made, will be education – both with respect to basic implementation of the Settings API, and with respect to implementation of the Settings API for more advanced uses and settings page layouts. We have no intention of creating any Guidelines that would be difficult or impossible to be met by the best-of-the-best Themes (the ones more likely to have advanced options and settings pages).

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc