WordPress.org

Theme Review Team

Tagged: Guidelines Toggle Comment Threads | Keyboard Shortcuts

  • Chip Bennett 1:22 am on July 9, 2014 Permalink |
    Tags: Guidelines, sane defaults, ,   

    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.

    Portability/DRY

    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() ), 
        themeslug_get_option_defaults() 
    );
    

    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( 
        get_theme_mods(), 
        themeslug_get_option_defaults() 
    );
    

    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() ), 
            themeslug_get_option_defaults() 
        );
        // Theme Mods API:
        /*
        return wp_parse_args( 
            get_theme_mods(), 
            themeslug_get_option_defaults() 
        );
        */
    }
    

    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.

        • David Gwyer 12:15 pm on November 14, 2014 Permalink | Log in to Reply

          You can filter the value of an existing option with the ‘option_’ . $option filter hook if you want to filter the options stored in the db.

          https://core.trac.wordpress.org/browser/tags/4.0/src/wp-includes/option.php#L112

          But I also like the idea of being able to filter the defaults array which haven’t been merged with the options yet.

        • Justin Tadlock 8:38 pm on November 27, 2014 Permalink | Log in to Reply

          I somehow missed Chip’s reply. Yep, you can filter option_{$option} if it’s already been saved. Then, check if the new setting is there in the array.

          Either method works fine. A hook on the defaults array will probably be easier for most people to understand.

          All of this makes me want to use the Theme Mods API anyway where each setting will have a unique filter hook.

    • David Gwyer 2:09 pm on November 14, 2014 Permalink | Log in to Reply

      Whilst looking over the above code it made me wonder if there is a case for core to merge defaults and options arrays together automatically, in get_option() or add_option() / update_option().

      If all themes are encouraged to handle defaults as described above anyway then why not make it part of core ensuring themes always had correct options entries even when new options were added to the defaults array.

      This would have the added benefit of not requiring themes to globalize/cache theme by taking advantage of the fact that results from get_option() are always cached. This is important because if theme options are updated anywhere between defining the global options variable and referencing it in code then you could be working with potentially invalid options data.

    • kevinhaig 6:46 pm on November 27, 2014 Permalink | Log in to Reply

      A little late for this comment, but when using the setting_API, and Customizer, all defaults are saved anyway. If that is the case why jump through all these hoops, and just save the options immediately the first time they are called.?

      • Justin Tadlock 8:43 pm on November 27, 2014 Permalink | Log in to Reply

        They’re actually not saved immediately when they’re called. For example, drop this piece of code anywhere in a plugin/theme:

        $example = get_option( 'an_example_option', 'an_example_default_value' );

        Load any page on the site. Then, check if the option is saved to your database in the wp_options table. It won’t be. WordPress won’t save this by default. It’ll only be saved when a user explicitly uses a feature (e.g., settings page, customizer) to save it.

        What we had before was that theme authors were saving defaults to the database so that theme options would work without the user visiting the customizer/settings-screen. The intention was very good, but the method was incorrect. Chip’s post is about using the correct method.

        And, there are a lot of real-world scenarios where saving to the database by default screws things up or won’t even work at all.

    • kevinhaig 2:08 am on November 28, 2014 Permalink | Log in to Reply

      Yes I understand that they are not saved immediately, however if you change 1 item and then save, all the defaults for the other items are saved. So the only time merging defaults is important is on new installs with themes when the options have not been adjusted at all, and the settings_API options entry has not been created. At least that is what I’m seeing in the database.

      • kevinhaig 2:21 am on November 28, 2014 Permalink | Log in to Reply

        To explain further, I have a ‘default’ => ‘value’ to all my add_setting() statements and these defaults are saved. I am assuming the only way around that would be to put nothing in the default?

        • Justin Tadlock 4:19 am on November 28, 2014 Permalink | Log in to Reply

          Technically speaking, you only have a single option as far as WP is concerned. That single option can have many “options” if it is an array (i.e., options within an option). So, yes, the other defaults are saved once you save one in that scenario because it’s all considered one option.

          You are half correct though about when it is important. The other half of that is handling new defaults on theme update for users who have already saved settings.

      • kuus 8:28 pm on May 27, 2015 Permalink | Log in to Reply

        This has changed in the 4.1 release, only the “items” or settings actually changed by the user get stored in the db. Even if they are all items of the same single theme_mods array. @see https://core.trac.wordpress.org/ticket/29983

    • cats_456 9:05 pm on December 9, 2014 Permalink | Log in to Reply

      I’m using this method for loading options and I have got a problem with the Customizer.
      1. If I load mods in the array on init hook to use them later, customizer refreshes all color settings back to the current state after using setting with ‘refresh’ transport (all changes made to color pickers disappear from visual view in customizer).
      2. If I load mods with get_theme_mods function customizer works like (1). If I change it to call to get_theme_mod function in cycle then it start working as intended:

      function theme_themeslug_get_options() {

      $defaults = theme_themeslug_get_defaults();
      foreach( $defaults as $key => $value ) {
      if( get_theme_mod( $key, -1 ) != -1 )
      $defaults[$key] = get_theme_mod( $key );
      }

      return $defaults;

      /* return wp_parse_args(
      get_theme_mods(),
      theme_themeslug_get_defaults()
      );
      */
      }

      So, now I load options in array twice and use get_theme_mod function to make Customizer refresh color settings … And it seems to work! Any ideas? This problem appears inside of the live preview only.

      • jashwant 3:26 pm on January 17, 2015 Permalink | Log in to Reply

        I guess, you are experiencing the same issue, I am experiencing. `get_theme_mods()` does not work because customizer uses the filter of `get_theme_mod()` to modify the values of options, but there’s no such filter in `get_theme_mods()`

    • jashwant 1:44 pm on January 17, 2015 Permalink | Log in to Reply

      Great article. I am not using the same structure in my theme.

      I am using `get_theme_mods()` and saving it in a variable, instead of calling `get_theme_mod()` for every option. I assume, this will definitely save a lot of db access.

      But, it is failing on customizer. When I change values from 1 of control, `get_theme_mods()` does not reflect that change.
      A little digging reveals that, `get_theme_mods()` does not have a filter, but `get_theme_mod()` has filter for each setting individually. When I looked further, I found that, this filter is being used by customizer to change the setting value, when I change something in 1 of the control.

      How can I avoid `get_theme_mod`, and use `get_theme_mods()` and still reflect the changes of customizer ?

      p.s. `get_theme_mod` does a db access on each call. Right ?

      • Justin Tadlock 6:37 pm on January 25, 2015 Permalink | Log in to Reply

        I’d actually argue that assigning the result of get_theme_mods() to a global is bad dev practice. The reason for this is that doing so bypasses the theme_mod_{$mod} core hook. This means that plugins, themes, and even WordPress might not perform correctly. Basically, don’t do it.

        Use the core functions instead of unnecessarily building something on top of that.

        As far as hitting the database, that’s not an issue. WordPress is going to auto-load those options when the page is loaded and cache them. Calling get_theme_mod() is going to do nothing more than grab the cached data.

  • Chip Bennett 8:05 pm on April 7, 2014 Permalink
    Tags: Guidelines, ,   

    How To Ensure Your Ticket Passes Final Approval Audit 

    Over the past couple of months, the number of approved tickets that have been reopened due to issues found during final-approval audit has declined, but many still get reopened. As a team, we want to ensure that tickets get approved (so that new Themes get added to the directory, and into the hands of end users), and we want reviewers to be able to take advantage of the incentive program.

    So I want to step through the things I check when performing a final review audit. We’re looking for some high-level and/or high-impact things that would cause problems for end users:

    Overall File Structure

    • Does the Theme look like it is derived from a common Theme (Underscores, Twenty Ten-Fourteen, etc.)? Are there included functional files that I’ll need to check. Are there asset folders (fonts, scripts, etc.) that I’ll need to check?

    style.css

    • Check ThemeURI and AuthorURI. Are they appropriate?
    • If ThemeURI or AuthorURI reference commercial Themes, are those Themes sold as GPL-compatible?
    • If the Theme appears to be derived, does it include a proper derivative-work copyright/license attribution?

    readme.txt

    • If the Theme has bundled resources/assets, are they listed in the readme with copyright/license attribution, or will I need to check file headers?
    • Is license for all bundled resources GPL or GPL-compatible?

    header.php

    • Are Theme options properly escaped on output?
    • Is favicon, if used, disabled by default?
    • Does the TITLE tag include anything other than the call to wp_title()?
    • Does wp_nav_menu() reference theme_location, and not menu?
    • Are any stylesheet or script links output instead of being properly enqueued

    footer.php

    • Does the Theme only use one credit link? Is that credit link exactly ThemeURI or AuthorURI, with no SEO-seeding of link text, title attribute, etc.?
    • Are any footer scripts output instead of being enqueued properly?

    index.php

    • Does template markup look generally appropriate?

    Front/Home Page Templates

    • Does the Theme have front-page.php? If so, is it used properly? Does it account for both a static page and the blog posts index as site front page?
    • Does the Theme have home.php? If so, is it used properly as the default blog posts index template?
    • Does the Theme have any custom page templates intended to be used as either front-page.php or home.php?

    comments.php

    • Does the Theme properly output wp_list_comments() for the comments list?
    • Does the Theme properly output comment_form() for the comment reply form, rather than hard-coding the form?

    page.php

    • Does the page template properly call comments_template()?

    functions.php

    • Are all functions and other things in the public namespace properly prefixed?
    • Is all functional output properly wrapped in callbacks and hooked into appropriate actions?
    • Is any of the functionality Plugin territory?
    • Does any of the functionality replicate core functionality?
    • Does the Theme use Theme options? Are they handled properly (single DB entry, proper settings page, sanitized on input, etc.)?
    • Do any of the Theme options replicate core options?

    This list comprises 99% of what I look for in an audit, and accounts for the vast majority of issues encountered that require reopening tickets. So, if you verify these things before resolving the ticket as “approved”, the chances that your ticket will get reopened will go down considerably.

    (Note: @emiluzelac may have other things to add to the list, for things he checks during an audit.)

     
    • ruphel 9:16 pm on April 7, 2014 Permalink

      Thanks for the checklist Chip

    • Emil Uzelac 11:47 pm on April 7, 2014 Permalink

      My process is very similar to @chipbennett and there is nothing more to add.

      I would like to say that rushing through reviews will most definitely resolve getting your ticket reopened. Take your time and you will be golden.

      Your time and efforts are greatly appreciated!

      For some weird reason, my post got published 4 times, sorry about that.

      • Rohit Tripathi 5:35 pm on April 8, 2014 Permalink

        One thing I would like to Add on behalf of @emiluzelac

        Make sure the themes have correctly spelt “WordPress”, with W & P in captals. I have seen this as a reason in many re-opened tickets.

        😛 :)

    • ThemeZee 7:28 am on April 8, 2014 Permalink

      “Does the Theme have any custom page templates intended to be used as either front-page.php or home.php?”

      Does this mean we are not allowed to use for example template-homepage.php for a custom front page template, but have to use front-page.php instead ?

      • Justin Tadlock 3:10 pm on April 9, 2014 Permalink

        home.php and front-page.php have very specific meanings in WP. They should only be used when they’re meant to be used. template-example.php, even if intended to be used on the front page, can also be used if the template can be used with any page.

        Personally, I prefer that devs make a custom page template that’s usable on any page. It offers more flexibility for users.

        • Chip Bennett 3:22 pm on April 9, 2014 Permalink

          Intent is important here. If it’s obviously intended as the site front page template, then it should be `front-page.php`. If the developer doesn’t necessarily intend for it to be the site front page, then call it a “featured content” template (or something similar), and name it `template-featured.php` (or whatever).

    • Jose Castaneda 11:25 pm on April 8, 2014 Permalink

      One of the things I often look for are hooks and filters. I’ve seen a few themes that register meta boxes and some that add post types. It just depends on how they are being used ( though post types should really be avoided in themes ).

      One thing I’ve learned is using the command line to my advantage and using grep to find all the add_action/add_filter calls a theme uses.

    • PageLines 12:30 pm on April 9, 2014 Permalink

      Thanks for the checklist guys!

  • Chip Bennett 2:53 pm on April 3, 2014 Permalink |
    Tags: Guidelines   

    Discussion: Theme Activation Standards 

    Currently, we are proposing a change to the Guidelines that would blanket-prohibit Themes from adding admin notices, redirects, or other similar functionality on Theme activation. The intent of the Guideline is to curtail the proliferation of nuisance/obtrusive Theme marketing in the user’s Admin.

    In the vast majority of cases, such activation functionality should not be needed. Themes are required to use add_theme_page() to add a Settings page, which ensures that end users can always find the Theme’s settings page under the Appearance admin menu. The new requirement for sane defaults will ensure that Themes will always work “out of the box”, at least at a baseline (i.e. no-broken-sites) level. The recommendation for Themes to hook settings into the Customizer will help ensure that end users can visually preview Theme settings changes via the core Customizer (Appearance -> Customize). And the Contextual Help API ensures that Theme developers can add as much rich-text setup/configuration detail as necessary.

    That said, there is still room for appropriate, standardized admin interventions on Theme activation. If we can agree on a consensus for standard admin interventions, then the Guidelines could reflect that consensus, and reviewers would have an objective standard to use when reviewing Themes.

    So, let’s discuss. What’s appropriate? What isn’t? How can we define appropriateness objectively?

     
    • Han 3:28 pm on April 3, 2014 Permalink | Log in to Reply

      How about adding admin notice about important changes of the new version? For example when we move the header and footer script, or custom css feature from theme to a plugin.

    • mudthemes 7:04 am on April 4, 2014 Permalink | Log in to Reply

      Even if the theme redirects the user after activation, the redirect must be to a page where only the documentation regarding the theme configuration is written.

      • eminozlem 5:51 pm on April 4, 2014 Permalink | Log in to Reply

        I think the extent may be defined with two rules a.) The redirected page should be theme’s page (most likely options page or documentation help page) b.) The page should be a related page and not advertising purpose page. Just like the same in many rules such as author & theme uri etc.

    • eminozlem 9:16 am on April 4, 2014 Permalink | Log in to Reply

      I don’t understand what’s the big deal with redirection on activation. It’s essential for themes with Option Framework that the options are initially saved for the theme to properly function.
      If you put your mind to it you can use anything out of its intended purposes so I think it’s not fair to punish everyone else because of the aggresive advertisers by prohibiting all kinds of redirecting / notice boxes that could otherwise prove useful.

      Semi OT: You mentioned sth. about the screenshot. I totally agree with that, screenshot guidelines shouldnt be that restrictive. After all, no theme ever really does look like the demo out-of-the-box. Screenshots should be allowed to display what theme might look like with proper modifications and / or content.
      Also I dont see any harm including other material in screenshot (like theme options). I mean some themes provide 4 theme options, others a hundred. It’d be eye-catching and easier for the user to spot the one for them if other aspects are allowed in the screenshot.

      • Chip Bennett 2:23 pm on April 4, 2014 Permalink | Log in to Reply

        Its essential for themes with Option Framework that the options are initially saved for the theme to properly function.

        This statement is untrue. Refer back to the Sane Defaults requirement. Properly implemented Theme options work out of the box, using developer-determined sane defaults, without any user configuration required. Themes that “break” if the user doesn’t configure Theme options have not properly implemented those Theme options.

        If you put your mind to it you can use anything out of its intended purposes so I think its not fair to punish everyone else because of the aggresive advertisers by prohibiting all kinds of redirecting / notice boxes that could otherwise prove useful.

        I do agree, which is why I’ve linked to a separate discussion, so that we can work out some meaningful standards/guidelines.

      • Chip Bennett 3:02 pm on April 4, 2014 Permalink | Log in to Reply

        It’s essential for themes with Option Framework that the options are initially saved for the theme to properly function.

        This statement is untrue. Refer back to the Sane Defaults requirement. Properly implemented Theme options work out of the box, using developer-determined sane defaults, without any user configuration required. Themes that “break” if the user doesn’t configure Theme options have not properly implemented those Theme options.

        If you put your mind to it you can use anything out of its intended purposes so I think it’s not fair to punish everyone else because of the aggresive advertisers by prohibiting all kinds of redirecting / notice boxes that could otherwise prove useful.

        I do agree, which is why I’ve linked to a separate discussion, so that we can work out some meaningful standards/guidelines. Please provide feedback there.

    • tskk 2:35 pm on April 4, 2014 Permalink | Log in to Reply

      I have opposed banning redirection in earlier discussion too, taking the user back to themes page after activation is meaningless, doesn’t serve any purpose, they have to click on theme options link and go select options anyway to get the best out of the theme. Wasting their time and effort is no good.

      Redirecting to theme options should be allowed.

      • Chip Bennett 3:07 pm on April 4, 2014 Permalink | Log in to Reply

        I disagree that user configuration of Theme options should be necessary. That’s partly why we’re adding a requirement for Sane Defaults. Users should know where to find the Theme Settings page should they choose to modify any of the defaults; users should not be forced to deal with settings configuration out-of-the-box.

        Theme-activation redirection UX is something that should be defined and handled by core, IMHO.

      • Frank Klein 3:21 pm on April 4, 2014 Permalink | Log in to Reply

        I disagree with this.

        When a user installs a theme, the experience should be the same, no matter what theme he just installed. Forcing the user to visit another screen without any action from his part makes the experience very confusing, especially if it doesn’t happen that way consistently.

        Imagine that you are a user. You found this great theme, installed it and activated it. The last thing you want to see is an options panel. You want to see how your site looks with this theme applied!

        Is the current theme activation experience as good as it can be? Probably not, but the Core team has been working on this, and they will continue to iterate on it. We should let Core handle this, because it is part of the core experience of WordPress.

        Themes should look good without having to configure options. Nobody likes setting up something, it is boring and often complicated.

        Also if a user can’t figure out quickly how to get a free theme to look like he wants, he’ll either post a support forum message or just download another theme. Either way that is not the outcome you want to achieve.

    • Devin Price 4:02 pm on April 4, 2014 Permalink | Log in to Reply

      I don’t think we should do a blanket-prohibition of admin notices. I am using two in the latest version of Portfolio Press if users are upgrading (so, actually, re-activation). One is a notice about important updates in the version, along with a link to a post about them. A second notifies users that they should update their Reading Settings. I think room should be left in the theme review guidelines for situations like this.

      I agree that upsell and marketing links should not be allowed on activation.

      I agree that notices about an option panel do not need to be displayed on activation. Users are becoming more aware about the “Customize” link. Good theme documentation can also help educate users.

      @eminozlem, Chip is absolutely right about defaults in Options Framework. You should pass a default when you call an option, e.g. of_get_option( ‘my-option’, ‘default’ ), if the theme requires something other than “false” as the reply if the option is not set. Does that make sense? Happy to explain more if needed: http://wptheming.com/contact

      • eminozlem 9:13 pm on April 4, 2014 Permalink | Log in to Reply

        Sure, my theme with OF does work defaults. But there are other specific reasons my implementation of the theme is better with an initial redirect (refresh) on activation.
        I agree with notices.The point is, no matter what the case is, be that notice, redirection, prompt or whatever, I think all should be allowed as long as it’s used in good faith and not in an abusive manner for marketing purposes.

    • @mercime 2:50 am on April 5, 2014 Permalink | Log in to Reply

      +1 blanket-prohibit Themes from adding admin notices, redirects, or other similar functionality on Theme activation.

    • CyberChimps 6:13 am on April 8, 2014 Permalink | Log in to Reply

      We’re strongly opposed to banning all theme activation notices.

      Some kind of default activation notice is required to alert users of a successful activation and what to do next.

      A better solution would be to have a default activation notice similar to what we’ve built into Responsive that directs users to theme options and documentation.

      In a perfect world, we’d all love if a theme just worked out of the box, but the truth is users need a help in knowing what the next step is to configure their website, and some customization will always be required, and the Customizer does not include all use cases yet.

      When .org forced us to removed redirects in our themes we saw significant increases in theme abandonment, and increased support from people who could not locate the theme options. Adding a customize button to the wp-admin bar is an illogical UI progression that most users don’t follow.

      Also, what about notices for companion plugins? Does this proposal intend to ban those as well?

      • Frank Klein 6:55 pm on April 8, 2014 Permalink | Log in to Reply

        TGM Plugin Activation notices or similar are not prohibited by this guideline.

        The Customizer has been introduced a while ago, and users definitely are getting used to it. Having to go to a separate options page to configure the front end of your website is more illogical than a contextually relevant and prominent link to the Customizer.

        I agree that there will always be users that struggle with setting up a theme, and we should help those. But I think that overly complicated themes are more to blame than the banning of admin notices or redirects.

        Instead of every theme shop rolling their own, we should use the feedback and experiences made to develop a Core proposal that will alleviate some of these pain points.

        • CyberChimps 12:21 am on April 17, 2014 Permalink | Log in to Reply

          The Customizer is fine for front end settings, but what about template configurations? Layouts?

          The Customizer is a great tool, but not an end to theme options.

          We would love standardized ways of addressing these pain points, which is why we would prefer if admin notices aren’t banned until a solution is actually in place.

      • Emil Uzelac 4:13 am on April 14, 2014 Permalink | Log in to Reply

        Companion plugins are excluded from the get-go and proposal does not affect them.

        Please note that @chipbennett was asking and not making solo decisions here, otherwise this post would not even exist.

        What is the best way to handle the activation and can we standardize?

        Emil

    • sanerdesign 10:22 am on April 8, 2014 Permalink | Log in to Reply

      I’m all for standardizing the theme activation notices rather than applying a blanket ban. I really feel that the admin notices can benefit the user if we can agree on the information that is displayed.
      This is just a suggestion, from my experience, but I think the following should be allowed in an agreed layout:

      Thank you message
      Link to developers site
      Link to the options if the developer isn’t just using customizer (optional)
      Link to that theme’s support pages

      It’s important to link to the developer in recognition of their hard work.
      A link to the theme options, I feel, is still important whilst they still exist. Theme options allow the developer to not just add options but to add a lot more information than they could on the customizer. Yes I am talking upselling (dirty word I know). Whilst we are probably all against over-the-top upselling and promotion of pro options etc we also have to accept that businesses are making money from this format and it is that money that pays for ongoing development and support of the theme. If we make it too difficult for developers to upsell we could end up with a lot of poorly supported themes that don’t get developed. I do think that this would be bad for the end user.
      The link to support pages is self explanatory but it is really important to let the user know immediately that there is somewhere to get help if they struggle with their chosen theme.

      Whilst I believe that it is the user experience that is always the most important for every action that we take we should consider the developer and their business for it will always be them that keep the WordPress themes fresh, supported and developed.

      Hugo

    • Schwarttzy 4:04 am on April 9, 2014 Permalink | Log in to Reply

      I don’t understand why after a theme gets activated that they get redirected to the page “Appearance.” Are they trying see how many themes they can activate in a minute or what? What’s so wrong with a page explaining the theme? Or possibly things they may want to do now that they activated this theme?

      Why is it so crucial that they get taken back to all the other possible themes they could change too?

      • CyberChimps 1:09 am on April 10, 2014 Permalink | Log in to Reply

        +1.

        Valid points.

        The explanation I was told was because they want to improve the on boarding process for WordPress, and there is some concern that a lack of selection for themes may be a pain point. However, they are simply creating a user experience nightmare with all of these new rules.

    • nikeo 2:13 pm on April 21, 2014 Permalink | Log in to Reply

      Hi,
      This follows a discussion with @chipbennet and @catchtheme during a theme review (https://themes.trac.wordpress.org/ticket/18164).

      We were wondering about the possibility to incorporate links into the top admin bar.
      In my case (Customizr theme), I have added a “Help” button in the admin bar which is visible both on back end and front end for a user connected.
      Users can have an almost direct link to the support forum on WP.org, the FAQ or the theme ‘s documentation if they feel lost. I think this makes the theme more user’s friendly and this is not redundant with the built-in WP links already displayed in this bar like : add a new post,/page…, link to dashboard, search, …

      Many popular plugins are elevating those kind of links in the admin bar and I think that’s often really interesting from a user experience perspective too.

      I would love to have your point of view/feedback about this and hope that we could come up with consistent guidelines for the WP themes.

  • Chip Bennett 2:35 pm on April 3, 2014 Permalink
    Tags: Guidelines   

    WordPress 3.9 Guidelines Revision Proposal: Round 2 

    Based on the previous discussion, the Guidelines proposal has been revised as follows. The proposed guideline change for Credit Links has been removed, and a proposed guideline change for Custom Logos has been added. Other proposals have been clarified based on previous discussion.

    The two most significant clarifications regard arbitrary header/footer scripts, and Theme activation.

    The proposed Recommended guidelines have not changed. While we understand the argument that there may not be consensus around certain implementations of features, we maintain that it is within the overall scope and objective of the Theme Review Team to encourage, facilitate, and drive best-practice consensus, and that it is in the best interest of end users to establish best-practice consensus. Thus, arguing that the Theme Review Team should not be establishing/promoting such best-practice standards in order to encourage consensus is moot – though we absolutely encourage discussion regarding what implementations should be considered/promoted as best-practice standards.

    Other Discussion Topics

    Screenshot

    I would be interested in discussing our screenshot requirements. It seems that “reasonable facsimile”, as a standard, isn’t really sufficiently meeting anyone’s needs. While the intent was to avoid blatant marketing via screenshot, the requirement tends to be taken so literally that developers cannot even display user-configurable features in their screenshot. This is especially limiting for Themes with featured-content front-page templates. As currently interpreted, the “reasonable facsimile” standard prevents the screenshot from displaying the featured-content front-page, because the featured content first has to be configured. So, let’s discuss a more sane/useful guideline for screenshots.

    Translation-Ready

    I would also be interested in discussing the establishment of at least some “best practice” guidelines for translation-readiness – primarily, proper i18n of strings. I think it is all but a given that, eventually, we should be requiring Themes to be translation-ready; but currently we don’t have objective standards to follow. The first step, then, is creating those standards, and then educating developers on them.

    Required

    Sane Defaults: Themes are required to use sane defaults.

    Themes must not save default settings to the database without explicit user action, and Themes must function properly out-of-the-box without user configuration (that is: if the user does not save settings, the Theme will still function properly)

    Bundled Plugins: Themes must not bundle Plugins.

    Themes may incorporate support for Plugins, and may integrate Plugin code directly into the Theme (if that Plugin code meets the presentation-vs-functionality requirement), but Themes must not bundle Plugins as a whole.

    Arbitrary Header/Footer Scripts: Themes must not provide Theme options for arbitrary header/footer scripts.

    Arbitrary scripts are non-Theme-specific scripts added to the document head or footer to provide non-Theme-specific functionality. Such scripts are Plugin territory, and pose a significant security risk if not handled properly.

    Custom CSS is acceptable, if properly sanitized.

    Note: this guideline does not apply to content “scripts” added to the template outside of the document head/footer, such as script widgets (Google Maps, Twitter Feed, etc.). Essentially, if a script can be hooked into the template via wp_head() or wp_footer(), then it falls under this guideline; otherwise, it does not.

    Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality on activation.

    Note: this guideline does not apply to admin notices such as TGM recommended Plugins (if implemented properly). I will open a separate discussion regarding consensus/standard “unboxing” admin notices. The purpose of this Guideline is to curtail the proliferation of unnecessary/obtrusive marketing in the user admin area, not to prevent legitimate, useful activation information for the end user.

    Theme Documentation: Themes must place any required documentation in a clearly marked readme file.

    Note: this guideline applies only to required documentation. Required documentation includes copyright/license attributions, Theme design constraints/limitations, description of non-standard Theme functionality, etc. Plugin-standard readme.txt is preferred, but not required.

    License: Themes are required to document in the Theme readme or license file the copyright/license attribution for all bundled resources.

    Themes are required to provide this documentation in the Theme readme file, regardless of where or how those bundled resources provide their own attribution. The purpose is to ensure that end users (and also, reviewers) don’t have to search for this important information, and to ensure that the developer has done due diligence to ensure that licenses for all bundled resources are GPL-compatible.

    Note: “blanket” statements for developer-owned resources (images, etc.) bundled with the Theme are perfectly acceptable. It is only third-party bundled resources that need to be listed explicitly.

    Custom Logos: If implemented, custom logos must be user-configurable, and disabled by default.

    This guideline will bring the handling of Theme options for custom logos in-line with the handling of Favicons. Currently, we require that “default” logos be generic/unbranded, but generic/unbranded logos are of no benefit to the end user. Likewise, Theme-branded logos are of no benefit to the end user. The most logical approach, then, is to require that custom logos not be displayed at all, unless the end user has configured one.

    Recommended

    Theme Documentation

    Themes are recommended to include a Plugin-standard readme.txt file.

    Themes are recommended to meet the WP core standard for inline documentation.

    Translation

    Themes are recommended to be translation-ready.

    Social Profile Links

    Themes are recommended to use a custom navigation menu when incorporating social network profile links

    Theme Options

    Themes are recommended to integrate Theme options into the core Theme Customizer

    Discuss

    Please discuss in the comments below.  If you have any additions to propose, please post them in the comments below, as well.

     
    • Rohit Tripathi 2:41 pm on April 3, 2014 Permalink

      +1 For Everything. Especially, the guideline change related to Screenshots. I hope it goes through.

      • Edward Caissie 4:19 pm on April 3, 2014 Permalink

        Aside from maintaining the premise of not allowing any sort of spammy / marketing type images I would be fine with opening the screenshots to something relatively easy to configure at installation provided how to create the screenshot’s “look” is documented in at least the `readme.txt` file … or similar documentation available to the end-user within the theme’s package.

    • tskk 2:57 pm on April 3, 2014 Permalink

      How much time do we have before recommendation of using theme customizer turns into requirement?

      • Chip Bennett 2:59 pm on April 3, 2014 Permalink

        Who knows? It’s something that may never happen. Right now, we just want to promote it as a best practice.

        Is there any particular reason not to want to integrate Theme options into the Customizer? I’m genuinely curious what those reasons might be.

        EDITED TO ADD: We made the Settings API *recommended* years ago, and have never made any move toward making it *required*.

        • tskk 3:03 pm on April 3, 2014 Permalink

          the left pane is very cramped,
          no framework like OF which has all the controls we need,
          no drag and drop setting/option

          • Chip Bennett 3:06 pm on April 3, 2014 Permalink

            True, the left pane can be a bit cramped – but I think they payoff (real-time preview of the setting change) more than compensates. Also, if you segregate your Theme options into logical sections, it makes the UI much more manageable.

            Almost every control imaginable is built-in to the API. Which one(s) are you missing, specifically?

            Can you explain the drag-and-drop? I’m not sure what you mean.

            • tskk 3:21 pm on April 3, 2014 Permalink

              The ability to use images in place of radio buttons like in optionsframework, ability to have a vertical accordion like i have in optionsframework. Is it possible to add stand alone text and maybe apply css to that text?

              If you see one of the cyberchimp themes, they have a drag and drop option where user can drag page elements around like reordering the site elements.

          • Zulfikar Nore 4:03 pm on April 3, 2014 Permalink

            I think with a little thought the drag and drop for page builders can also be integrated in the customizer.

            My thoughts here are based on the new incoming Widget control section which has some drag and drop options for the widgets.

        • tskk 2:08 am on April 4, 2014 Permalink

          Also customizer doesn’t have a reset button, import/export option.

          • Schwarttzy 4:12 am on April 9, 2014 Permalink

            import/export would be sweet for the customizer

    • daveshine (David Decker) 3:39 pm on April 3, 2014 Permalink

      *Tranlation-ready* should totally be REQUIRED!

      Why?
      Translations are essential, and I never understand why an international used platform like WordPress.org/themes should promote untranslateable themes in the year 2014+ ?!?

      *Translation-ready* also means a theme can be customized with another tone/ type/ of the same language, for example, still in English (but use British English, formal tone for business etc.).

      Also, to have it as a requirement will improve overall theme code and quality – and especially make them more user-friendly! And not to forget, it will all help prepare for upcoming launch of language packs (that are prepared in core, but “not yet launched” here on .org for themes, plugins).

      Standards:
      There are already standards all there, for years already:

      • load_theme_textdomain()
      • load_child_theme_textdomain()
      • all the translation functions for strings like __(), _e() plus all the related stuff there…
      • using sprintf() and printf() to keep as much markup as possible out of translation strings
      • using _x() context translation functions to add context to strings and/ or be better help for translators

      I don’t know any reason why *Translation-ready* should not be required for any theme here (and plugins also!)? So, if someone has such a reason for me, I am eager to know what speaks against all that.

      As a international developer and user I am fighting the good fight for years already, to get more and more themes, child themes and plugins translateable at all, and moreover to have them in the “standards” (see points above). WordPress.org theme repository should be the leading example in this field!

      PLEASE make it a requirement! Thanks so much!

      Dave from Germany :)

      • Chip Bennett 3:55 pm on April 3, 2014 Permalink

        I agree that making it *required* is our end goal. But we have to start somewhere. We have to have an established, objective string-translation standard. Then we have to educate developers how to implement it – and we have to educate reviewers how to evaluate Themes against it. We’re simply not ready for that.

        I want to get there. We need to get there. I agree that WPORG-hosted Themes should all be translatable. But we’re simply not at the point that we can make it required, and be able to enforce it fairly and consistently.

      • Ulrich 4:55 pm on April 3, 2014 Permalink

        I think it would be great if every theme and plugin were internationalized. From my experience reviewing themes a number of theme developers do not have a deep understanding of PHP so they find it difficult to internationalize the theme. By placing it as a requirement we are increasing the level of entry. Do we really want to do that?

        Somehow I think it is a theme developers decision to choose to support i18n or not. Users can show the demand by asking for i18n support.

        We did once discuss what is needed for a theme to be allowed to use the translation-ready tag. At the time we decided that all strings had to be internationalized and the header should contain the text domain but does not need to include a POT. How far do theme reviewers enforce best practices for creating strings?

      • Justin Tadlock 5:01 pm on April 3, 2014 Permalink

        I’m one of the biggest supporters of theme authors internationalizing their themes that you can find. I’ve done this myself for many years. However, I cannot get behind this being a requirement, at least at this point in time. The reason for this is that it is a huge barrier to entry. I probably would’ve never made my first theme if I had to do this.

        We need to start with education. I’d also like to see all articles in the Codex and Handbooks that provide code examples with text strings to actually show those strings with the proper functions.

      • Sami Keijonen 5:30 pm on April 3, 2014 Permalink

        I’m with David here. Make it required. This has been in theme/plugin development best practice for so long that it should be required. I don’t mind if it makes a little bit harder to get your theme on WP.org. It should be about quality, not quantity.

        Do you have data how many new themes are not Tranlation-ready?

      • wpweaver 8:02 pm on April 8, 2014 Permalink

        I am 100% for making theme translatable on the front side (visitor view).
        But, as usual, my theme (Weaver II) is on the extreme edge of things.

        It has a very complex admin interface, full of long, complex, and technical descriptions. It uses complex HTML and scripts to make the admin user interface work with its hundred of options.

        Making this in a translatable form (it has LOTS of direct HTML output) is next to impossible. And this doesn’t even mention how difficult it would be to get technically correct translations.

        But for the visitor side, my theme has already been translated to something like 25 languages, and that number is growing.

        So – visitor side translation capable – REQUIRE asap.
        admin side translation capable – leave recommended.

    • Frumph 3:45 pm on April 3, 2014 Permalink

      … no, no and no.

      If you want to write up guides and point to them to the designers, go for it.

      • daveshine (David Decker) 3:54 pm on April 3, 2014 Permalink

        Yes, sometimes to much guides/ guidelines make things more complicated and could take away some passion…!

        However, it’s not only about design here: it’s also about usability, security of code, making stuff translateable, avoiding aggressive marketing in themes etc. Over the years, the experience was some guidelines should be in place.

        • ruphel 12:17 am on April 4, 2014 Permalink

          With David 100% on this one.,make it rquired

    • Morgan Feeney 3:47 pm on April 3, 2014 Permalink

      Theme options in the customizer! The purpose of which is for live preview of your website, including styles, now widgets too, so why exclude any other content which can be edited on the back end from this?

      It makes total sense to me, I am a designer and front-end guy and I think it would be of benefit.

      if WordPress is to carry on competing on a global scale with new and existing CMS, anything which enables a real-time preview into how the site looks with on-the-fly changes being made only makes it a stronger contender in the long-run.

    • Zulfikar Nore 4:13 pm on April 3, 2014 Permalink

      +1 on all proposed changes!

      The Screenshot issue has been too stringent – allowing for configurable options to be included in the screenshot is a sane proposal.

    • Justin Tadlock 5:07 pm on April 3, 2014 Permalink

      I still disagree with the requirement for license info to be placed into readme.txt. WordPress itself uses a license.txt file for this. I’d be more supportive of this if we allowed for license info to be placed in either license.txt or readme.txt.

      • Emil Uzelac 5:42 pm on April 3, 2014 Permalink

        Wiki has nice readme.txt example:
        http://en.wikipedia.org/wiki/README

        • README General information
        • AUTHORS Credits
        • THANKS Acknowledgments
        • ChangeLog A detailed changelog, intended for programmers
        • NEWS A basic changelog, intended for users
        • INSTALL Installation instructions
        • COPYING / LICENSE Copyright and licensing information
        • BUGS Known bugs and instructions on reporting new ones
      • Chip Bennett 5:55 pm on April 3, 2014 Permalink

        I’m fine with that; I’ll update the post accordingly.

      • Catch Themes 3:22 pm on April 5, 2014 Permalink

        Yes I agree with Justin… It should be either readme.txt or license.txt.

    • Ron 5:23 pm on April 3, 2014 Permalink

      Most of the guidelines seems to be in order but I have to disagree with the Custom Logo being disabled by default. Unlike the favicon, a logo affects the overall design of a theme.

      Currently, we require that “default” logos be generic/unbranded, but generic/unbranded logos are of no benefit to the end user. Likewise, Theme-branded logos are of no benefit to the end user.

      True, but what about one that is not visible? There might not be any benefit to the end user whether a custom logo is enabled or disabled by default but then why make it a requirement?

      If the generic logo requirement isn’t good enough then maybe we could even have a standard logo image for every theme with a logo option to use. Maybe a WordPress logo?

      • Chip Bennett 5:55 pm on April 3, 2014 Permalink

        You might be misunderstanding what “disabled by default” means. It just means that, if the user configures a logo, then that logo is output; otherwise, if the user does not configure a logo, then no “default” logo is output.

        I’d be curious to see an actual case where a “disabled by default” custom logo would adversely impact a Theme’s design.

        • Ron 6:10 pm on April 3, 2014 Permalink

          Yup, that’s exactly how I understood the guideline. It might not be a very big difference but a visible logo helps a user envision the overall look of the theme after he/she either removes or changes it.

          My point is, are there actual benefits at all from a custom logo being either enabled or disabled by default that would command it to be a requirement? If there aren’t any then this would just unnecessarily add to the growing set of guidelines.

          • Chip Bennett 6:20 pm on April 3, 2014 Permalink

            Yes, there are actual advantages. A company is very likely to have a pre-defined logo that they would then configure for use with the Theme. But an individual (or even a non-commercial entity or group) likely won’t have a logo. For them, it is detrimental to have an arbitrary image (or worse: an image that says “Logo”) prominently displayed on their site. (Note: it would be equally bad to have an image displaying the Theme name prominently displayed on their site.)

            This is not an onerous guideline. It simply means wrapping the logo output in if ( '' != $themename_options['logo'] ) {}.

            • Ron 6:50 pm on April 3, 2014 Permalink

              A company is very likely to have a pre-defined logo.
              An individual (or even a non-commercial entity or group) likely won’t have a logo.

              Is this really the case? I think a user, whether intending a theme for company or individual use would decide on what theme to use basing on it’s looks (screenshot & preview). The visibility of a logo and seeing its positioning helps make that decision. I think it’s pretty reasonable to expect a user who chooses a theme that has a logo option, to use one. I think the fact that logos are required to be user-configurable is good enough.

              I’m not really that much against it but I just can’t see the guideline as an actual benefit to warrant being a requirement.

            • Chip Bennett 9:26 pm on April 3, 2014 Permalink

              I doubt that users primarily base their decision on whether or not a Theme supports a custom logo, nor should individuals be barred from using a Theme simply because it outputs a logo, and they don’t have or need one.

              The decisions to add this guideline is born out of the numerous instances of logos being problematic during the review/approval process. This guideline actually simplifies things for Theme developers, who no longer have to come up with a “generic/unbranded” logo to output by default (most of the time, Themes have had a Theme-branded default logo, and had to go to the extra effort to create an unbranded logo).

        • Catch Themes 3:26 pm on April 5, 2014 Permalink

          I think the only problem with this will be in Theme Preview. If we have option to make that logo available in preview then there will be no effect on design. For example in Catch Kathmandu theme, I added in generic logo just to show in Theme Review at http://wp-themes.com/catch-kathmandu/

    • Emil Uzelac 6:20 pm on April 3, 2014 Permalink

      +1 for all @chipbennett!

      • alex27 10:34 am on April 4, 2014 Permalink

        I totally agree with Chip on the logo. What good does the fancy custom logo does to the user anyway, when theme authors do not provide source files to customize it (not that I think we should require it).

    • Codice e Bella 2:47 am on April 4, 2014 Permalink

      I only developed my first theme for the repository about a month ago. While I created a very basic and simple theme to learn the process so that I could start developing themes that weren’t so “basic”, I didn’t think learning to develop it as translation-ready was that difficult. Someone else said it should be about quality, not quantity. Even as a new developer to the theme repository, I would agree with that, and say making it a required practice shouldn’t stop someone from developing new themes for the repository.

    • mudthemes 6:57 am on April 4, 2014 Permalink

      Screenshot Proposal is brilliant.

      To make it more transparent, why not ask theme developers to include the exact method used to achieve the screenshot in readme.txt or link the plugins/widgets used to create it.

    • Frank Klein 11:47 am on April 4, 2014 Permalink

      Screenshot

      I think that the screenshot should reflect the intended use case of the theme, so a blogging theme (like TwentyThirteen) should show the blog index. A theme with a front page template (like TwentyTwelve) could show this specific template.

      I’d argue though that themes should always show the front page (whether a blog index or static page). It is okay to have a screenshot that shows user-configurable options already set up. However the screenshot should not contain elements that are dependent on the installation of plugins.

      Translation-Ready

      I would be in favor of making this a requirement. I agree with Justin Tadlock that this represents a further barrier to entry for theme developers. But I would say that we need to think about the users first and only then about the developers.

      With an increasing number of WordPress users that don’t have English as their native language, themes that are not translated are effectively useless. So in this case, we should side with the users and make this a requirement.

      I would also add that Internationalization is no longer a mystery or novelty. With the amounts of tutorials and WordCamp talks on this subject, learning this is not an issue.

      Custom Logos

      I agree fully with this. Custom logos are an option. As such they should optional.

      Licensing information

      Having a file (whatever name it has) that contains all the licensing information for the theme is a big help for reviewers. It also makes the life for users easier that want to use themes for their own projects, as they don’t have to worry about finding out what licenses apply to the different elements of a theme.

    • Devin Price 4:09 pm on April 4, 2014 Permalink

      +1 for all these changes.

      I think we should put a note about how to properly enqueue Google fonts as this has come up a lot in my recent reviews. It could also perhaps be somewhat automated: https://github.com/Pross/theme-check/issues/6

      I would also love to get more theme support for translations. Perhaps there is a better way to match theme developers who are knowledgeable in this area with developers who wish to learn it?

    • Catch Themes 3:32 pm on April 5, 2014 Permalink

      +1 for the changes. Ready to work on Theme Review. Will need to adjust some on my themes as well. Thanks :)

    • Scott Smith 2:18 am on April 7, 2014 Permalink

      How should I be escaping Custom CSS? I crawled the internet for a while and wasn’t able to find a helpful bit of advice on this.

      • Frank Klein 12:00 pm on April 7, 2014 Permalink

        Id’ say that you can use htmlspecialchars(). Make sure to pass the blogs charset to it along with the appropriate quotes flag: htmlspecialchars( $css, ENT_QUOTES, get_option( ‘blog_charset’ ) );

    • Catch Themes 12:49 pm on April 17, 2014 Permalink

      Has this guideline been finalize. Can we use this proposed guidelines while review new themes. WordPress 3.9 is out now. But I don’t see final guidelines.

      • Chip Bennett 12:57 pm on April 17, 2014 Permalink

        New Guidelines are typically enforced one month after final release, to allow sufficient time for adoption.

  • Chip Bennett 2:28 pm on February 7, 2014 Permalink
    Tags: Guidelines   

    WordPress 3.9 Guidelines Revisions Proposal 

    It’s just about that time again, with the WordPress 3.9 release just around the corner. We’ve taken a few release cycles off from making any major changes to the Guidelines, so now is a good time to take a look at what we can improve. To kick off the discussion, the admins propose the following revisions to the Guidelines:

    Required

    Sane Defaults: Themes are required to use sane defaults.

    Themes must not save default settings to the database without explicit user action, and Themes must function properly out-of-the-box without user configuration (that is: if the user does not save settings, the Theme will still function properly)

    Bundled Plugins: Themes must not bundle Plugins.

    Themes may incorporate support for Plugins, and may integrate Plugin code directly into the Theme (if that Plugin code meets the presentation-vs-functionality requirement), but Themes must not bundle Plugins as a whole.

    Arbitrary Header/Footer Scripts: Themes must not provide Theme options for arbitrary header/footer scripts.

    Arbitrary scripts are non-Theme-specific scripts added to the document head or footer to provide non-Theme-specific functionality. Suchscripts are Plugin territory, and pose a significant security risk if not handled properly. Custom CSS is acceptable, if properly sanitized.

    Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality.

    Theme Documentation: Themes must place any required documentation in a clearly marked readme file.

    Required documentation includes copyright/license attributions, Theme design constraints/limitations, description of non-standard Theme functionality, etc. Plugin-standard readme.txt is preferred, but not required.

    License: Themes are required to document in the Theme readme file the copyright/license attribution for all bundled resources.

    Themes are required to provide this documentation in the Theme readme file, regardless of where or how those bundled resources provide their own attribution. The purpose is to ensure that end users (and also, reviewers) don’t have to search for this important information, and to ensure that the developer has done due diligence to ensure that licenses for all bundled resources are GPL-compatible.

    Theme Credit Links: ThemeURI and AuthorURI, if both are used, must be from distinctly separate sites.

    Using both ThemeURI and AuthorURI is not required, and if only one is appropriate, then only one should be used. ThemeURI is a resource specific to the Theme. AuthorURI is a resource specific to the developer. For example, a Theme shop really only needs to use examplethemeshop.com OR examplethemeshop.com/themes/theme-slug. There’s really no need for both. Likewise, a non-commercial individual really only needs to use exampleperson.com OR exampleperson.com/blog/post-about-theme-slug. There’s really no reason to use both. But, if an individual has a ThemeURI of github.com/authorname/theme-name, and an AuthorURI of exampleperson.com, that’s totally appropriate.

    The intent here is to try to drive the focus of ThemeURI and AuthorURI back to being *end user* resources, first and foremost: information about the Theme, or a way to contact the developer. This clarification will hopefully eliminate some of the issues regarding appropriateness of ThemeURI/AuthorURI.

    Recommended

    Theme Documentation

    Themes are recommended to include a Plugin-standard readme.txt file.

    Themes are recommended to meet the WP core standard for inline documentation.

    Translation

    Themes are recommended to be translation-ready.

    Social Profile Links

    Themes are recommended to use a custom navigation menu when incorporating social network profile links

    Theme Options

    Themes are recommended to integrate Theme options into the core Theme Customizer

    Discuss

    Please discuss in the comments below.  If you have any additions to propose, please post them in the comments below, as well.

     
    • tskk 2:34 pm on February 7, 2014 Permalink

      I have seen reviewers asking authors to declare license for images which are part of the theme, do we authors need to? if so how? do we have to list all images used in the theme and declare their license?

      Also will the recommendations be migrated to required any time soon?

      • Chip Bennett 3:02 pm on February 7, 2014 Permalink

        Yes, bundled images must have licenses declared. If the developer created the images, then it is fine to state that they are copyright the developer, and released under the Theme’s license.

        • tskk 3:42 pm on February 7, 2014 Permalink

          but do we have to list them like :
          Filename.png – License ?

          If a theme has multiple skins, the list will be huge.

          • Rohit Tripathi 3:55 pm on February 7, 2014 Permalink

            We can do it folderwise. All images inside a particular folder fall under one license. And the ones in a different folder have a different license.

      • Chip Bennett 3:05 pm on February 7, 2014 Permalink

        Some things added as *recommended* are there as a phased approach toward *required*; others are not; they are simply there as a best-practice recommendation.

        • tskk 3:28 pm on February 7, 2014 Permalink

          Is theme customizer going to be required? if so how much time do we have? its going to be major overhaul for many themes.

          • Chip Bennett 3:32 pm on February 7, 2014 Permalink

            If there’s ever a timeline, we’ll communicate it. For now, this is the “get it on people’s radar” phase. :)

            And, it really isn’t a huge overhaul at all, if the Settings API is implemented properly. It takes minimal code to extend the Customizer via the Customize API.

      • fernandot 9:04 am on February 16, 2014 Permalink

        What about the changelog?

        It’s strange that there are complete guidelines for plugin submission that require a special readme.text file with a section for change log and there aren’t the same guideline for themes en the official repository.

        It’s frightening to update any theme with no information about the changes that you’re going to approve, while with plugins you are plenty informed about what is gonna happen.

        I’m truly concerned about this absence of mandatory for themes since they are the face of our sites. And yes, of course, I can make a child theme for my customizations but the problem remains the same: I don’t know what it is gonna happen when I update a theme from the repository.

        Why?

        Cannot this be changed?

        • Chip Bennett 11:17 pm on February 16, 2014 Permalink

          I agree with you in part, but the reality is, with the current infrastructure, even if we required Themes to include a Change Log, there would be no way to expose that Change Log to end users, either via the WP-Admin back-end, or via the Theme’s directory listing page. End users would have to pull up the Theme’s directory listing, then dig through the SVN files to find the readme or change log file.

          Also: requiring a change log would not ensure that all Theme developers add consistently useful and detailed information for each update.

          So, requiring a change log would not guarantee any real benefit to end users. Ensuring that end-user benefit is a long-term objective that will have to include changes both in what is required of Theme developers and also in the Theme directory infrastructure.

          • fernandot 5:29 pm on February 17, 2014 Permalink

            I agree with you, also in part :)

            I understand your complaints but I really believe that it could be a great benefit for users. You only visit the updates page in your dashboard and, if there is any update for plugins and themes the difference is huge and, in case of themes, a question of faith.

            As for plugins there could be mandatory to submit a change log, if plugin developers can do it (most of them no profit) more easy for theme developers to require because they are the main interested in promote their themes in repository, as a lot of them sell themes (profit).

            It’s my opinion as heavy user and WP consultor for some companies that demand it to me.

            • Chip Bennett 1:39 pm on February 18, 2014 Permalink

              The point is: we could require a Plugin-standard readme.txt for Themes, including Change Log and Update Notices, but it wouldn’t change anything. As far as I know, WordPress doesn’t parse Theme readme.txt files in order to display Update Notice on the Upgrades page. The infrastructure isn’t in place, the way it is for Plugins.

    • Inekris 2:52 pm on February 7, 2014 Permalink

      Just some clarification for non-English readers might come in handy.

      • By ‘must not’, the actual meaning is ‘are not allowed to’, ,ie, it is a binding restriction
      • By ‘end-user’, the person(s) actually administering, or have acces to the back-end of the site, not the readers.

      I know these questions might seem silly, but assumptions are the root of all screw-ups, so better safe than sorry.

    • Sami Keijonen 2:53 pm on February 7, 2014 Permalink

      I would definitely require translation-ready.

      It doesn’t encourage to use Plugin-standard readme.txt file, when it’s not used anywhere in .org site.

      Other than that guidelines seems good to me.

      • Chip Bennett 3:03 pm on February 7, 2014 Permalink

        I would, too; but we’re simply not ready. Consider making translation-ready formally *recommended* as the first step toward eventually making it *required*.

        • daveshine (David Decker) 9:09 pm on February 14, 2014 Permalink

          Can explain further what “we’re simply not ready” means? Is that regarding “Language Packs” or such?

          It should be required that all themes are translation-ready — that has nothing to do with language packs directly, though it would need no extra work if language packs happen for themes then… :)

          When I give support for my plugins, one of the biggest issues are bad internationalized themes or those that are not translation-ready at all.

          Any GOOD WordPress theme should be translation ready, if it is not, than it is no good theme IMHO, no matter how it looks…! :)

          • Chip Bennett 11:12 pm on February 16, 2014 Permalink

            “We’re simply not ready” means that Translation itself isn’t mature enough as a properly implemented feature to be *required* at this point. It’s a matter of education, not one of infrastructure. I agree that the ultimate goal is to require translation for directory-hosted Themes; but we need to ensure that implementing that requirement doesn’t raise the bar unreasonably high. Right now, it would. 90% – perhaps even 95% – implementation is fairly simple. But it is that 5-10% of string translation that prevents us from making it a requirement at this time.

            Full disclosure: I personally lobbied to propose that we make “translation-ready” a requirement in this go-round. But I agreed with the rest of the admins (and others queried) who argued that, as a whole, we’re just not ready to make it a strict requirement. So the approach we would like to take is to emphasize translation now, by making it *recommended*, and then setting some future end date, probably tied to a future WordPress release, at which time we will increase the criticality to *required*. And in the time in-between, we will put effort into educating developers regarding proper/best-practice implementation of translation.

      • Chip Bennett 3:06 pm on February 7, 2014 Permalink

        Note: there are (long-term) plans for readme parsing. Those plans will first include the Plugin-standard readme file, and will hopefully be extended to include others (readme.md, for example). So, making it *recommended* at this time is a first step in that direction.

    • Ulrich 3:02 pm on February 7, 2014 Permalink

      Just to clarify the readme file can also be a readme.md?

      I would like to see a Child Theme and Tags section.

      • Chip Bennett 3:07 pm on February 7, 2014 Permalink

        Yes, at this time, the readme file can be any clearly identified format (readme.txt, readme.md, README, etc.)

        I’m not sure what you mean by Child Theme and Tags section?

        • Ulrich 4:03 pm on February 7, 2014 Permalink

          What I meant have a guidelines for child themes. Something along the lines of “Child themes need to be functionality wise or design wise different to the parent theme.”

          There is no clear guideline what the theme needs to achieve to be allowed to use a certain Tag. accessibility-ready being the exception here.

    • Rohit Tripathi 3:22 pm on February 7, 2014 Permalink

      I don’t think Custom Navigation Menu for Social Profile Links is a Good Idea.

      +1 for everything else.

      • Chip Bennett 3:25 pm on February 7, 2014 Permalink

        Why don’t you think it’s a good idea? What are the disadvantages?

        EDIT: I have ulterior motives for this question. I’m presenting on the concept at WordCamp Dayton in a month, and would love to know any issues/problems/disadvantages with the concept, so that I can try to address them.

        • Rohit Tripathi 3:41 pm on February 7, 2014 Permalink

          Truly speaking. I can not think of a way in which it could be implemented. If you could provide a link to a theme, which implements social icons using custom menus, then I could provide better feedback on this.

        • kevinhaig 3:44 pm on February 7, 2014 Permalink

          The two themes I have use a widget for social links. It seems odd to add social links to a menu that is usually crowded to begin with.

          • Chip Bennett 4:09 pm on February 7, 2014 Permalink

            But a menu is just a “list of links”. A bunch of social profile links are a form of a “list of links”. Where it gets placed and how it gets styled is completely up to the developer.

            • kevinhaig 4:18 pm on February 7, 2014 Permalink

              I agree, however so is a social widget. So why is it recommended over a widget or other methods?

            • Zulfikar Nore 4:20 pm on February 7, 2014 Permalink

              Another problem that might arise here is the different icon fonts that are available. Are we going to say that all developers use one specific icon font set i.e. genericons?

            • Chip Bennett 4:21 pm on February 7, 2014 Permalink

              A social Widget is fine as well, but may not be as tightly integrated into the Theme. The recommendation is that the custom nav menu implementation is recommended over Theme Options or other Theme-specific implementations.

            • Chip Bennett 4:21 pm on February 7, 2014 Permalink

              Why would the icon font matter, if the Theme defines the CSS? :)

            • Zulfikar Nore 4:24 pm on February 7, 2014 Permalink

              So if theme A defines the CSS for Genericons and theme B defines its social menus as Font Awesome how would that carry over to the new theme?

              The user will still have to redo the menu won’t they?

            • Chip Bennett 4:37 pm on February 7, 2014 Permalink

              Why would the user have to redo the menu? A menu is just a group of “menu-item” post-types that get output as HTML list items. The separate Themes define the separate CSS to style the separate implementations of the social custom nav menu.

        • Ulrich 4:14 pm on February 7, 2014 Permalink

          This will be difficult for theme with another solution to switch.

          Is there a solution to do it with images and not icon fonts?

          • katmoody 4:28 pm on February 8, 2014 Permalink

            I’m newer here but wanted to jump in … hope that’s okay?

            This is my default way of handling menus for clients and I have done them with images, sprites and Font Awesome … maybe having a default would be a good idea. Justin Tadlock has a post that uses the same idea of a social menu but utilizes CSS selectors for the different social networks – which would make it possible to have lots of different social networks included without having to have them in the same order within the menu OR having to add class names. I can’t remember if he used Font Awesome with that example or a different one, but it works well and could be a great default.

            Theme authors could utilize hooks to change it around, use images, use an image sprite, or even just use text links …

            As for themes that already have a solution in place – that’s pretty easy – you just don’t display the menu (deregister it?)

            As for Justin’s work … both his Social nav posts are worth reading to understand how this could be done:

            http://justintadlock.com/archives/2013/08/07/social-media-nav-menus

            http://justintadlock.com/archives/2013/08/14/social-nav-menus-part-2

      • bassjobsen 3:39 pm on February 7, 2014 Permalink

        Can you give an example of a custom navigation menu for social profile links? I don’t understand what this mean at all.

        • Jose 7:23 pm on February 7, 2014 Permalink

          I know Stargazer, ( already mentioned ), I think Konstantin K’s Expound ( might ?) I know sorbet has it and uses really well. It’s just a simple way of creating a social links area without having to store/lose that information within themes. since menus are saved and theme options vary from theme to theme.

      • Ulrich 4:16 pm on February 7, 2014 Permalink

        @jeffr0 How did you find using it on wptavern?

        • Jeff Chandler 4:25 pm on February 7, 2014 Permalink

          I love the way Stargazer utilizes an icon font for social icons. It does limit the ability to use different icon images to represent social services but the icon fonts have the look and colors of the services and it’s portable so I’m willing to take the good over the bad.

          The only other potential downfall is if you want to make the icons larger, you must increase the icon font size. If you are using one icon font declaration in the CSS for use of icons across the entire site, adjusting the size will adjust all of them. Doesn’t work out so well if you only want the icons within the social menu larger instead of the entire site.

          • Chip Bennett 4:29 pm on February 7, 2014 Permalink

            The icon colors are actually defined via CSS – at least for Genericons. Also, because you can use specific CSS IDs and class names for custom nav menus, you can target your social menu specifically for adjusting the font size.

            • Jeff Chandler 4:31 pm on February 7, 2014 Permalink

              Yeah, I realize it’s just CSS and with the right CSS, I could increase the social icons by themselves without messing with the rest of the site. So not really a good or bad thing, just a means of how they are setup.

      • Konstantin Obenland 4:36 pm on February 7, 2014 Permalink

        Having a hard time to find a place for this comment. :)

        Even as (only) a recommendation, I think we are steering in very muddy territory here. While using the menu functionality to provide social links may be a good way to provide a somewhat portable social links experience, in reality it is not. There are no standards surrounding an implementation, so even if two themes use menus for it, it may very well be that they are still not compatible with each other.

        There are plenty of other, valid ways out there to provide social links. IMO it is not the place of the Theme Review Guidelines to recommend one approach over the other, especially without any kind of core provided support for a truly portable solution.

        We don’t recommend a specific way or script to implements sliders, we don’t tell theme authors how Featured Content should be done, we don’t recommend using `li`s over `div`s in comment list markup. Why would we recommend how to implement Social Links?

        • Chip Bennett 4:40 pm on February 7, 2014 Permalink

          The biggest advantage of the custom nav menu implementation is that the user retains user-created content (a group of links to social network profiles) when switching Themes. It is terrible user experience for a user to have to enter 6-10 social network profile URLs as Theme options every time the user switches Themes.

          And the implementation has no adverse impact. If a Theme doesn’t use it, the user still has to input the Theme options, and simply doesn’t apply the social menu to any of the Theme’s defined Theme Locations. It’s as if that menu doesn’t even exist.

          • Konstantin Obenland 4:43 pm on February 7, 2014 Permalink

            I’m not disputing that it is one of the better ways to provide that functionality.

            I’m saying that the Theme Review Guidelines have no place in even recommending it, without explicit core support.

            • Chip Bennett 4:46 pm on February 7, 2014 Permalink

              My comment above addresses this, but I see no problem at all with the Theme Review Guidelines adopting as “recommended” things that are best-practice implementations. That’s partly why some things are “recommended” rather than “required”.

              And core *does* have support for the implementation: the custom nav menu feature.

        • Konstantin Kovshenin 4:43 pm on February 7, 2014 Permalink

          Compatibility really just means the way the navigation menu location is called. In Stargazer and Expound it’s social, if all themes used the same theme location, it will all just work out of the box. If they use a different slug, well, the user will have to just assign their existing menu to the new location. If they don’t use wp_nav_menu(), the user can just assign their existing menu to a sidebar widget.

          In any case, the user will not have to re-enter their links to their social profiles every single time they switch a theme.

          • kevinhaig 4:54 pm on February 7, 2014 Permalink

            Usually if a user switches a theme, it’s for a longer period, and minor adjustments are not a big deal, in my opinion.

            However don’t you feel these kind of recommendations ultimately dampen the creativity of a theme development?

          • Chip Bennett 5:35 pm on February 7, 2014 Permalink

            While we want to defer to the developer’s prerogative regarding design intent and aesthetics whenever possible, I fail to see a “creativity of Theme development” argument in this case. We’re talking about a list of links.

          • Chip Bennett 6:08 pm on February 7, 2014 Permalink

            Since the Theme can define the menu CSS ID and class names, it’s really unnecessary to rely on a given custom menu name at all. The user merely needs to assign the correct menu to the correct Theme Location. Same with a Plugin that makes use of a menu Widget.

        • Chip Bennett 4:45 pm on February 7, 2014 Permalink

          I should also add: sometimes, the best way to *create* a standard is to pick an implementation, and then encourage its adoption. That’s been true for the Theme Hooks Alliance (outside of the Theme Review Team), Post Formats implementation, and many other features.

          To my knowledge, there is no better, more-portable way to implement social network profile links integrated into a Theme, than to use the custom nav menu method. So, unless and until a better method comes along, it is a net benefit to end users to encourage the best-known method as an adopted best-practice.

          • Konstantin Obenland 5:25 pm on February 7, 2014 Permalink

            sometimes, the best way to *create* a standard is to pick an implementation, and then encourage its adoption.

            Is it the WPTRT’s job to create a best practice?

            To my knowledge, there is no better, more-portable way […]

            That is a bad reason to create a recommendation. If anything, developers should be encouraged to come up with new, unique, and better ways. And of course there are already other ways of doing it out there!

            • Ian Stewart 10:03 pm on February 7, 2014 Permalink

              Another +1 to Konstantin’s points here.

            • Chip Bennett 10:14 pm on February 7, 2014 Permalink

              So, Konstantin and Ian: you both think it is a bad idea, and detrimental, for the Theme Review Team to promote and facilitate consensus around best practices? Really?

              I must strongly disagree with that position. Who better to educate and promote regarding best practices, and to help build consensus around those best practices? It is in the best interest of the WPTRT – and more importantly, it is in the best interest of end users – for WPTRT to engage in consensus-building around best practices.

              And promoting one implementation as recommended because it is the *current* best practice does not preclude the later development of *better* practices.

            • Emil Uzelac 10:40 pm on February 7, 2014 Permalink

              I will have to agree with Chip here, promoting best practices is not bad idea at all. Also why shouldn’t we educate?

      • Konstantin Kovshenin 4:36 pm on February 7, 2014 Permalink

        Just to clarify, using wp_nav_menu() to display links to social profiles doesn’t mean you have to use Genericons, or any icon font at all. You can still use sprites or images, that’s up to your theme.

        • Chip Bennett 4:37 pm on February 7, 2014 Permalink

          THIS. That’s the beauty of the implementation.

        • Zulfikar Nore 4:40 pm on February 7, 2014 Permalink

          That still does not make it portable from theme to theme as Konstantin Obenland points out above.

          • Chip Bennett 4:42 pm on February 7, 2014 Permalink

            How so? It’s always there. And someone could write a Plugin to define the CSS, and allow the social profile menu to be used, for example, in a sidebar Widget, regardless of the Theme.

            100% portability, with or without explicit Theme support.

            • Zulfikar Nore 4:43 pm on February 7, 2014 Permalink

              Then lets make it a “Plugin territory” in that case – always portable in terms of user defined links as well as the icons :)

            • Chip Bennett 6:05 pm on February 7, 2014 Permalink

              Why swing the pendulum that far that direction – too far in that direction, IMHO?

              If a Theme is designed such that social profile links are displayed in the site header (or footer), for example, you could do that with a dynamic sidebar. But that’s a lot of unnecessary hoops for both the developer and the end user, when the developer could simply output wp_nav_menu() in the desired location, and be done.

      • Justin Tadlock 5:36 pm on February 7, 2014 Permalink

        I want to provide a little feedback and answer a few questions on the whole social nav menu idea since I originally proposed it. This isn’t a direct response to Rohit only, but to all who have asked.

        The original article is here: http://justintadlock.com/archives/2013/08/07/social-media-nav-menus This shows how to create the menus with and image sprite.

        The updated tutorial is here with Genericons: http://justintadlock.com/archives/2013/08/14/social-nav-menus-part-2

        Those two posts go into quite a bit of detail and answer some of the questions some of you might have.

        I originally came up with this concept for a theme called Socially Awkward. After testing its success with users, I later added it to a theme called Stargazer. Both themes are on WordPress.org. Since then, it has picked up a little steam with other theme authors implementing it.

        The main reason for this concept was to handle data portability. The idea is that a user can create a nav menu with their social links. These can be used with nearly any theme either via a theme’s nav menu locations or widgets. They’re simply menu items.

        The cool part is that theme authors, if they choose, can define styles like what I’ve done with Genericons to make these menu items look cool without the user having to do anything other than select the nav menu location for a particular theme. It doesn’t require them to re-enter information or know the names of CSS classes to have their social menus look cool.

        This is but one approach to social profile links. I think it’s pretty cool. However, I don’t think it should be listed under “recommended”. What I’d really like to see is a separate section on the Make Themes site for “cool things you should try”. To me, this is nothing more than a resource that we should promote, which should be separate from the guidelines.

        • kevinhaig 5:07 am on February 8, 2014 Permalink

          +1 Justin

          I think your idea of social links is a very cool one, and I will look into it more.

          I also love the idea of a section on things to try.

          I just don’t like the idea of it being recommended, as developers will tend to gravitate to this solution as it is classified as a best practice. I’m not against best practices by the way, just not in this case. As theme developers move to this proposed best practice, it will in my opinion limit other creative ways of presenting social links.

          • Chip Bennett 1:01 pm on February 8, 2014 Permalink

            The idea is for developers to gravitate toward a consensus best-practice, because that gravitation leads to consistency for end users. It’s always important to be open to new and creative ways to do things, and that certainly applies here. And of course, a specific core-implemented solution would trump all.

            • kevinhaig 2:44 pm on February 8, 2014 Permalink

              I agree that consistency for end users is a good thing, but I think it’s important to balance that with creativity. Creative design also has a huge impact on the user experience.

              Incorporating social links into a menu is a great idea and an option that will fit many themes. But in some themes it may make better sense to go a different route.

              I think in this case it’s very a minor impact on the user experience, and as such I don’t feel it warrants being considered a best practice.

              Enough said….I do appreciate these kinds of discussions Chip! It’s one of the things that makes WordPress so great :)

            • Chip Bennett 3:07 pm on February 8, 2014 Permalink

              I agree that creativity is important, and I believe in deferring to the developer’s design and aesthetic prerogative. But, I just don’t see how this recommendation in any way hinders or infringes developer design. Bear in mind that we’re simply talking about HTML markup here – HTML markup for a “list of links”. Semantically, that’s a UL with a bunch of LIs. I don’t recall any Themes that are doing anything meaningfully different with the markup for their social profile links. Likewise on the back-end: the “list of links” is generated by a set of Theme options. There’s no “creativity” there. The Theme options are entirely utilitarian.

              The real creativity here is in the design/style of that markup – and that creativity is in no way hindered by using a custom nav menu to output the list items, or by having the user input their “list of links” via the custom nav menu UI rather than via the Theme settings UI. In fact, it’s the real beauty of this implementation. Want to use an icon font? You can. Want to use a different icon font? You can do that too. Want to use images or an image sprite? You can do that, too. It’s all defined in the CSS, by targeting link attributes.

    • bassjobsen 3:41 pm on February 7, 2014 Permalink

      I should make the standard readme.txt required

    • kevinhaig 3:53 pm on February 7, 2014 Permalink

      I’m not sure I fully understand the Arbitrary Header/Footer Scripts requirement.
      In themes I have developed I allow the user to set up a copyright strip at the bottom of the page, by entering an html line in a custom option panel. This allows them to set up links (for example designer links, or sitemap links). Is this what you are talking about?

      • Chip Bennett 4:12 pm on February 7, 2014 Permalink

        Links should be added as a custom nav menu. But a line of HTML is HTML, and not a script. In this case, “script” refers to an actual script, just as javascript or jquery.

    • Frank Klein 3:57 pm on February 7, 2014 Permalink

      Concerning the theme activation, the proposed guideline is “Themes must not implement activation redirects, admin notices, or similar functionality.”

      Does this exclude admin notices generated by something like the TGM Plugin Activation class?

    • Mel Choyce 4:18 pm on February 7, 2014 Permalink

      Any chance for allowing multiple theme authors any time soon?

      • Rohit Tripathi 3:27 am on February 8, 2014 Permalink

        Even I Look forward to it! Let’s hope its added sometime in future,

    • Chip Bennett 4:24 pm on February 7, 2014 Permalink

      Unfortunately, that one’s outside of our control/scope. That’s an issue with the WordPress.org Theme Directory itself. If the infrastructure supported multiple authors, the Theme Review Team certainly would as well.

    • Konstantin Obenland 4:26 pm on February 7, 2014 Permalink

      Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality.

      “Similar functionality” is extremely soft. The Theme Foundry recently started to integrate “unboxing” messages right after activating themes. That has received nothing but exceptional feedback on WordPress.com, but would probably fall under this guideline. It is also not clear that while admin notices are forbidden in general, it is fine to display them in the context of plugin recommendation. I understand how redirects can be confusing, I don’t like the direction of the other two.

      Theme Credit Links: […] a Theme shop really only needs to use examplethemeshop.com OR examplethemeshop.com/themes/theme-slug. There’s really no need for both.

      I understand the requirements around each URL, I do not understand how having one makes the other obsolete. I think it is reasonable for a theme author to specify both URLs, respecting the current guidelines in place. The links are currently only visible to users in the Appearance menu, and have no effect on the front-end. If anything they provide users with more context, and avenues to get support. This would be one of the rules that seem arbitrary and overreaching.

      • Zulfikar Nore 4:28 pm on February 7, 2014 Permalink

        +1

      • Jeff Chandler 4:29 pm on February 7, 2014 Permalink

        Just a question but is this guideline also in reference to Helpers that can be used to provide a tour of the theme when it’s activated. Would those violate this guideline

        • Chip Bennett 4:35 pm on February 7, 2014 Permalink

          They already do. Core defines those as a core-only functionality. Unless/until core considers them to be open to use by Themes/Plugins, they’ll be disallowed. (That’s been true since their inception.)

          • Jeff Chandler 4:43 pm on February 7, 2014 Permalink

            Wow, and here I am constantly telling developers they should add helpers to their plugins or themes after activation so I know where to go to configure them. Now I feel bummed out for giving bad advice,

      • Chip Bennett 4:34 pm on February 7, 2014 Permalink

        I’d love to see some UX feedback on types of activation messaging/help/etc. The intent is to prevent misuse/abuse, not to prevent legitimate user assistance.

        As for the credit links: again (and unfortunately), the problem is the misuse/abuse of them. If they’re useful and appropriate, they’re generally going to pass.

        And as with most Guidelines, exceptions can be granted with sound justification. These Guidelines that get into subjective areas are very difficult to write objectively. It will always be a work-in-progress to improve and clarify them.

        • Konstantin Obenland 4:39 pm on February 7, 2014 Permalink

          These Guidelines that get into subjective areas are very difficult to write objectively.

          Ha, I remember it being the biggest challenge for me, when I started reviewing themes! :)

          But I really don’t see how only allowing one link rather than two improves that. It doesn’t change the nature of the linked content. It does not help in solving the challenge of subjectivity.

          • Chip Bennett 4:41 pm on February 7, 2014 Permalink

            It’s not that only one link instead of two is being allowed; rather, it is that the two links provide meaningfully different information.

            • Zulfikar Nore 4:56 pm on February 7, 2014 Permalink

              somethemeshop.com as author url provides meaningful info about the author and somethemeshop.com/blog/theme-slug has meaningful info on the theme.

              If that is the desired end result then why are we saying that is no longer acceptable? Or even considering it?

              The abuse/misuse is when neither of the links are relevant and meaningful in context right?

            • Chip Bennett 5:36 pm on February 7, 2014 Permalink

              If you’re landed on somethemeshop.com/blog/theme-slug, what are the chances that you can’t or wouldn’t find your way tosomethemeshop.com?

            • Zulfikar Nore 5:57 pm on February 7, 2014 Permalink

              The chances are pretty good but I still think we should not penalize authors for using their themeshop/dev site as author url under the guise of misuse/abuse.

              As long as the two are relevant to the theme then I say its perfectly fine to have them included.

            • Chip Bennett 6:01 pm on February 7, 2014 Permalink

              I don’t think it’s a matter of “penalizing”. The Theme URI and Author URI really aren’t publicly exposed (except for the one used as footer credit link). They’re entirely for conveying information to the end user.

              The ultimate point we’re trying to convey is that the links should be useful for conveying relevant information to the end user.

        • Zulfikar Nore 6:23 pm on February 7, 2014 Permalink

          I think the requirement should then be “If both theme url and author url are used” they “must be” relevant as in conveying….

          (a) Information about the author and
          (b) information about the theme.

          If the two conditions are not met then the url is not allowe be it the author or theme url.

          To outright say that author url is not allowed is a bit too restrictive IMHO!

          • Chip Bennett 6:30 pm on February 7, 2014 Permalink

            And to outright say that Author URL is not allowed is not the intent. :)

            In my mind, this mainly impacts:

            1) Theme shops. A Theme shop isn’t an “author”; an author is a person. So, a Theme Shop landing page is, from the end user perspective, redundant with the Theme’s page on the Theme shop’s site.

            2) Individual Theme developers who have a valid Author URI, but then use what amounts to a “hey, I released this Theme” blog post as Theme URI. Generally, such a blog post provides no additional, meaningful information for the end user from what is already provided by the Author URI.

            (Now, Otto’s example, where the developer provides a static page with Theme documentation, information, maybe support links, etc.? Entirely appropriate as Theme URI.

            I’m just struggling with the right words to articulate the difference.

      • Ulrich 4:59 pm on February 7, 2014 Permalink

        @obenland Do you think you could share a screenshot of what The Theme Foundry has done?

      • Ian Stewart 10:02 pm on February 7, 2014 Permalink

        +1 to both these points.

      • Emil Uzelac 10:48 pm on February 7, 2014 Permalink

        I would definitely love to see an example and users feedback as well.

    • Justin Tadlock 5:18 pm on February 7, 2014 Permalink

      I wanted to bring up some of these points in the admin exchange on this a couple of days ago, but I’ve been a bit busy this week. Now that I’ve had some time to sit down, here’s my response to the required points.

      Sane Defaults: This is something we’ve been pushing for some time. It’s definitely needed.

      Bundled Plugins: I agree on this as well, but I want to reiterate what I’ve previously said in this discussion to make sure we’re not taking this too far. Here’s the link: http://lists.wordpress.org/pipermail/theme-reviewers/2014-January/017291.html

      Arbitrary Header/Footer Scripts: +1

      Theme Activation: Agreed for the most part. However, I wouldn’t be entirely against all things like this. I’d like to see a particular implementation first before making an overarching decision on all features.

      Theme Documentation and License: Disagree in parts, particularly with copyright/license attributions. A license.txt file works just fine for this purpose. As long as the theme makes copyright and license clear, that’s all I care about.

      On the subject of readme.txt, I don’t believe we should be dictating much of anything that goes into that file. It should be treated **exactly** like that of the plugin directory.

      I also see this as largely another stumbling block for theme authors. I’d rather them focus on making great themes than having to figure out the complexity of doing a readme file the correct way. By and large, it has nothing to do with theme development and everything to do with what a few of us would like to see.

      Theme Credit Links: Strongly, strongly disagree. I simply can’t get on board with this at all. If I wanted to give justintadlock.com as my author URI and justintadlock.com/themes/example as my theme URI (what I used to do before having a separate theme site), I can’t think of a valid reason not to allow that. One of the earliest reasons for the theme review team was to prevent spam and people trying to game the system in some way. That’s the reason we check the author and theme URIs.

    • Samuel Wood (Otto) 5:32 pm on February 7, 2014 Permalink

      I disagree with the credit links. If I made a theme, I most certainly would use an Author URI of http://ottopress.com and a Theme URI of http://ottopress.com/themename or similar to that, and yes, that would be perfectly valid.

      To disallow this is not an acceptable “requirement”.

      • Chip Bennett 6:02 pm on February 7, 2014 Permalink

        Clearly, as-written, it’s not articulating what we’re trying to get after. That’s why we’re having the discussion: to generate the feedback necessary to articulate what we’re trying to accomplish.

    • Zulfikar Nore 6:35 pm on February 7, 2014 Permalink

      I totally agree with point #2

      But for #1….For most theme shops – the shop is the developer (a team effort) and therefore they are essentially the author.

    • Zulfikar Nore 6:38 pm on February 7, 2014 Permalink

      OK, I don’t know why this landed down here but it was in response to: https://make.wordpress.org/themes/2014/02/07/wordpress-3-9-guidelines-revisions-proposal/#comment-33797

    • Chip Bennett 6:44 pm on February 7, 2014 Permalink

      “Essentially the author” – but that’s not the intent of Author URI.

    • Jose 7:49 pm on February 7, 2014 Permalink

      I am for most of the things. I, too, will have to agree with Otto and Justin with credit links. We just have to use our best judgement when it comes to that. :)

      As for the readme I think it should be recommended not required.

      • Chip Bennett 8:01 pm on February 7, 2014 Permalink

        Yep – the intent of the credit links was to get wording out, and to get feedback. Expect changes there. :)

        And regarding the reaadme: the only thing that’s changing is that we’re specifying the location for any *required* documentation. Previously, we stated that certain things were required to be documented, but didn’t say where. So, we’re clarifying that the location for required documentation is in the readme file.

        The *format* of the readme is being recommended as the Plugin-standard readme.txt, but we’re not proposing that it should be *required* to be in that format.

        • Jose 8:09 pm on February 7, 2014 Permalink

          Gotcha! That makes a little more sense now. :)

    • Chip Bennett 8:06 pm on February 7, 2014 Permalink

      Regarding admin notices: would it be helpful to clarify that any admin notices must be related specifically to Theme setup, and not advertising in nature?

      • Ulrich 9:37 pm on February 7, 2014 Permalink

        Yes, I am working on an extension of the current activation notice. This is what I have created.
        http://grappler.tk/screenshots/Screenshot-20140205001.jpg

        It is only displayed once when the user activates the theme the first time. There is no advertising.

        • Chip Bennett 10:10 pm on February 7, 2014 Permalink

          That is certainly unobtrusive, but is it *necessary*? It merely provides a link to the Theme Options page – a page that is in a standard location that is the same for all Themes. I see this more as a user education issue than a real need.

    • CyberChimps 10:14 pm on February 7, 2014 Permalink

      “Theme Activation: Themes must not implement activation redirects, admin notices, or similar functionality.”

      This a bad move that will hurt users experience, and continue to cause user confusion.

      What we need is a core solution to the problem such as what I mocked up here: https://twitter.com/trentlapinski/status/428995176426532865/photo/1

      The reason we got rid of redirects was so people can switch between themes quickly without being redirected, a reasonable move. What this also did unfortunately was confuse first time users, increased theme abandonment rates, as well increases in support from people asking where the theme options went.

      First time users need hand holding to let them know where to go to setup their theme, find documentation, and support. We absolutely need some kind of method to on-board users to setup their themes for the first time. The current theme activation notice is useless, and doesn’t tell anyone anything.

      This is why my team and I are developing the concept above, and are hoping to get it in core and would love the Theme Review Admins to encourage we add a standard way of on-boarding users for all themes.

      On Social Profile Links: Poor solution, can we please figure out a better one? I think we need a core solution to this as well.

      On Theme Options in favor of the Customizer: Again not a good solution. The Theme Customizer is half baked, and the version of the Customizer is embarrassing compared to WordPress.com. It was implemented into Core way too soon, and needs to be refined and polished before it can ever be considered as a longterm solution to theme options.

      On that note, Theme Options are not going away even if we perfect the Theme Customizer. For example, how can we ever add drag and drop functionality to the blog or define settings for archives and templates from the theme customizer? You can’t, Theme Options aren’t going anywhere. Again would love a core solution or some kind of options framework for everyone to use, which would make a lot more sense, but forcing people to use the Customizer to do things it was never intended to do isn’t the solution either.

      • Chip Bennett 10:21 pm on February 7, 2014 Permalink

        “What this also did unfortunately was confuse first time users, increased theme abandonment rates, as well increases in support from people asking where the theme options went.”

        Has this been supported anything other than anecdotally? I’d love to see user testing on this point, and would certainly support solutions that resolve demonstrated UX issues.

        “On Social Profile Links: Poor solution”

        Why is it a “poor solution”? Please elaborate.

        “On that note, Theme Options are not going away even if we perfect the Theme Customizer.”

        You are correct. The Theme Customizer doesn’t replace Theme Options. At best, it could (potentially) replace Theme *Settings Pages*. Themes would still have to use either the Settings API or the Theme Mods API to define, save, and use Theme options. The recommendation is added only because it is beneficial to end users, and actually helps resolve the issue you mention above – because if Theme Settings are incorporated into the Theme Customizer, then end users can configure Theme Options and activate their Theme in one, single action.

        “…but forcing people to use the Customizer…”

        Recommended != Required. No one is being “forced” to do anything.

        • CyberChimps 10:56 pm on February 7, 2014 Permalink

          Seeing as we can’t track users we don’t have the kind of hard data wish we had to definitively prove this.

          All we know is we’ve seen an increase in first time users in our support forums who can no longer find our theme options since 3.8 was released and we had to remove our redirects. We’ve also seen an increase in theme abandonment since 3.8 which we are assuming is due to people who do not know what to do once the theme is activated and can’t find the theme options or our support forums. All we can do is track what happens in our support forums and listen to what users tell us, and ever since 3.8 was released we’ve seen increased confusion as to what to do after a theme is activated.

          We could even simplify it to something like this: https://i.imgur.com/mgtRBVV.jpg Or anything really that gives the user some kind of direction to go in after a theme is activated. Again the purpose of this is to give a first time user a guide on what to do next. The new activation notice does not accomplish this.

          As for the Social Profile links, again this is something that I think needs to be either addressed in Core or in a plugin. Almost all themes I’ve seen use stylized social icons, using the menu system for assigning links to icons is confusing. While a clever work around, I don’t even want to think about the support nightmare this is going to cause.

          As for the Customizer, again at most this can only be recommended for now. I was speaking about in the future of possibly requiring the Customizer.

          • tskk 11:03 pm on February 7, 2014 Permalink

            I too would like to redirect users to theme options page after activation, Redirecting theme there is helping them use the theme better.

          • Emil Uzelac 12:19 am on February 8, 2014 Permalink

            I will still stand against the redirects.

            The image you presented us with seems harmful and if really is beneficial and if it doesn’t cause any issues, maybe we can work something out. Nothing is written in stone, right?

            • Zulfikar Nore 7:53 am on February 8, 2014 Permalink

              +1.

              I’ll also stand against redirection.

              How about hooking in to the “Theme Actions” section on the active screenshot? A theme options button next to the Customize button sort of thing.

              You could also be innovative and add a secondary button below the current “Theme Details” on hover and maybe that too could open in a modal window with help details? Or better still, hook in to the current modal and details there?

              Just throwing some ideas around :)

            • Chip Bennett 1:04 pm on February 8, 2014 Permalink

              Here’s my suggestion for an improved workflow:
              https://core.trac.wordpress.org/ticket/26899

            • tskk 1:27 pm on February 8, 2014 Permalink

              That would need all themes to use customizer ditching the theme frameworks we use.

            • Chip Bennett 1:40 pm on February 8, 2014 Permalink

              No, it wouldn’t. Why do think that it would?

              Whatever options framework you use itself uses either the Settings API or the Theme Mods API. The Customizer doesn’t replace either of those APIs, and in fact, *requires* and relies on the use of one of the two APIs. The Customizer is merely a different *front end* for settings. Hooking into the Customize API doesn’t change anything at all with any of your current Settings. It can (but doesn’t have to) replace the Theme Settings page. But your options framework? It doesn’t replace that; in fact, it *can’t* replace that – and without your options framework, the Customizer wouldn’t work at all with your Theme’s settings.

        • nikeo 1:12 pm on February 8, 2014 Permalink

          +1 for this https://core.trac.wordpress.org/ticket/26899
          => Lot more advantages than drawbacks to me from a user experience perspective

        • Zulfikar Nore 2:04 pm on February 8, 2014 Permalink

          The proposed customizer redirect although has some advantages it will only benefit themes that have adopted the Customizer as the means for theme Settings.

          IMO it is defeatist on two counts …

          (1) It will go against the grain of “No Redirection” stance.
          (2) Bad user experience to land on an empty Customizer (except for the defaults) if the developer uses a custom options framework.

          We all seem to assume that all first time users are “dumb” so lets spoon feed them when the emphasis should be on educating them and then let them find their way to those places where they can better understand the facilities and use them effectively.

          • Chip Bennett 2:23 pm on February 8, 2014 Permalink

            You’re missing the point. The Customizer isn’t a “means for theme Settings”. It’s merely a front end that *exposes* existing Theme settings. It doesn’t change the way that Themes handle settings, at all. Not one bit. It’s just an alternate front-end – and a darn useful one, I might add, because of the real-time preview of changes.

            1) The Themes UI already includes a “customize and activate” link for Themes. It’s not a redirection; it’s merely part of the Theme-selection workflow. In fact, the Customizer is invoked before the new Theme is ever even active, allowing for user configuration and preview of settings before that configuration ever appears on the site front end. This is freaking awesome UX, not “defeatist”.

            2) I don’t think you’re understanding what the Customize API is or how it works. Unfortunately, that seems to be a somewhat widespread problem. We’re attempting to help alleviate that misunderstanding/problem by encouraging Theme developers to hook their existing options into the Customizer – emphasis on *existing*. Nothing changes, except that the Theme settings auto-magically get exposed in the Customizer. The Theme’s handling of those Settings doesn’t change. Not at all. Not even a little bit. Your Settings Page still exists (though if you wanted to, you could get rid of it). Your Settings framework still exists. Your Theme Settings are still added via register_setting(), still get passed through your defined sanitization callback when saved, and are still called via get_option(). None of that changes.

            Nothing “defeatist” there. Just awesome UX made available to the end user.

            “We all seem to assume that all first time users are “dumb” so lets spoon feed them…”

            That’s actually pretty ironic, given that the reason that I argue against Theme activation admin notices is because we should be educating users about where the standard location for a Theme Settings page is. Users aren’t dumb, and we don’t need to treat them as such. We’re merely *recommending* that Themes hook into an awesome API that provides a sweet end user benefit (real-time preview of settings configuration). It has nothing to do with users being dumb (not true) or with a systemic lack of educating users about basic WordPress UI (true, and a failure on the part of developers, not users).

    • PeterRKnight 4:04 pm on February 8, 2014 Permalink

      Just to be extra clear does a bundled plugin mean actually packaging the files with the theme?
      Or does it also apply when using an activation class that downloads & activates a plugin separately during the activation process?

      • Chip Bennett 4:06 pm on February 8, 2014 Permalink

        Activation scripts are fine. In that case, the Plugin files are not actually bundled with the Theme; the user downloads and installs the Plugin from the WPORG Plugin Directory.

        Bundled Plugins refer to Plugins for which the Plugin files are physically bundled with the Theme.

    • alex27 6:14 pm on February 10, 2014 Permalink

      Regarding Arbitrary Header/Footer Scripts – it’s still allowed to add a field for Custom CSS to be outputted in header, right?

      • Chip Bennett 2:31 pm on February 11, 2014 Permalink

        Quoting directly from the post:

        Custom CSS is acceptable, if properly sanitized.

    • wpweaver 7:43 pm on February 17, 2014 Permalink

      RE: Header/Footer scripts

      This is a good idea in theory, but….

      It seems to me the requirement overlooks a serious problem. The thought is that is plugin territory, but it isn’t in this case because there is no way to have a plugin get into header.php or footer.php. No actions, no usable filters.

      So say I want to add a video script right below or above my header image. The header image typically gets inserted in header.php by each theme, right? If not a video, then there are other examples of external sites providing a plugin script one might want in the header/footer – I know of some musician sites that provide very nice links to players and the like via scripts. But you can’t get modify that code from a plugin. I’ve tried to write that plugin, and I don’t know how to do it. There is no support from the core to do that. As far as can tell, doing so will require a new standard hook or something that all themes need to call from header.php and footer.php. To me, this is a huge gap in the API.

      So it is not a reasonable requirement. Unless that is not what you mean – stuff coming from header.php and footer.php. Or unless I missed something fundamental about how header.php and footer.php work.

      • wpweaver 7:56 pm on February 17, 2014 Permalink

        A good compromise requirement would be to only allow scripts in the header/footer from users with an appropriate user role.

        • Konstantin Kovshenin 7:59 pm on February 17, 2014 Permalink

          That would actually be a bad compromise because it’s insecure. You can’t assume that everybody is using the same set of capabilities for specific roles. For example, on many networks the unfiltered_html capability is turned off for everyone, even for the super administrator role.

          • wpweaver 8:00 pm on February 17, 2014 Permalink

            Role/capability – whatever.

          • wpweaver 8:04 pm on February 17, 2014 Permalink

            I’m after a bigger point – I think non-programmer but competent site admins should be able to insert a script to a musician’s player – or whatever – right below the header image (or above it, or after the title – don’t want to nitpick), or into the footer. These kind of needs exist. Banning scripts from header.php/footer.php would totally preclude this option from anyone other than someone with the ability to go in and modify PHP code. That is not a good option for “mere” mortal users.

            • Chip Bennett 1:44 pm on February 18, 2014 Permalink

              The Theme can provide template hooks (such as THA), or competent site admins can use a Child Theme to add the desired scripts.

              Again, an actual use case would be helpful here.

      • Konstantin Kovshenin 8:01 pm on February 17, 2014 Permalink

        You should check out the wp_head and wp_footer actions.

        • wpweaver 8:06 pm on February 17, 2014 Permalink

          Yeah – I have. Tell me how to do what I just said with those action? Let’s see – wrap header.php with output buffering, capture that, parse it, find the right place to insert the code. Yeah, right.

          • Konstantin Kovshenin 8:13 pm on February 17, 2014 Permalink

            Output buffering? We’re talking scripts here, ones that go in the head section of the site, or before the closing body tag in the footer, that’s pretty standard. Unless you’re referring to mid-page inline js-code, which users can already insert using the editor (if they have the necessary capabilities).

            • wpweaver 8:25 pm on February 17, 2014 Permalink

              And that is my point. A”mortal” user doesn’t have the “necessary capabilities. But they could fill in a box that says “Insert before site header image” or “Insert above menu” or “Insert after site title” – places the theme author can add the the code in “header.php”. This is a reasonable thing for people to want to do – so some with unfiltered_html should be allowed to do that without having to have a programming degree – or the level of comfort of editing PHP file.

              (Which of course is a terrible idea any way. Don’t know why that editor is still there! Change theme functionality via child themes only!!! Just HATE people even hinting of editing theme files! Nothing but trouble.)

              May we could put a little box up “I want to put this script in my header area. I promise to be a good person, and that I have the right to do this, and that the script does only nice things. I am aware of security issues.”.

              But header.php must output everything from …

              typically

              . So what I’m talking about is the stuff in the site content header – title, image header, menus. That’s where an average user wants to easily add extra HTML and nice scripts, and where there is no way for a pluging to get access to the code that generates that content. A theme option is the only feasible way to do that.

            • Konstantin Kovshenin 8:31 pm on February 17, 2014 Permalink

              So what you are referring to is various places in the theme where users should be able to “inject” their inline javascript code. Can you provide more use cases to what a user would insert “after site title” and “above menu” and “before header image”?

              Also, have you considered adding custom actions to the various places you would like users to inject code, and then using a plugin to inject the js during those actions? Finally, if you’re looking at standardizing such actions across many themes, you should take a look at the “Theme Hook Alliance” initiative.

          • wpweaver 9:07 pm on February 17, 2014 Permalink

            OK – a use case. I can’t find the music player script I’ve used in the past, but…

            Let’s say there is a site – say Google Maps – that provides nice little scripts to anyone that supports its latest and greatest features. Features that one one has yet provided a plugin to do. So maybe not google, but say great-maps-startup.com. To use this new feature, you have add the script source somewhere – by lets say in the HEAD block. So my theme has an option “Add to HEAD Section”. The user copy/pastes the block right in there. (or the footer if it should be at the end.) A plugin could enqueue the script, but plugins don’t keep up with all the sites that do offer such scripts.

            And if you are fussy, and want to do exactly what you want to do, sites like Google Maps will generate exactly the script you need to show whatever map you want. Things a plugin might not do. Things someone who can read the instructions at the site can follow, and copy and paste.

            The whole point of allowing this option is to let the site owner make the decision, and have the tools needed to add scripts where they need to be added. We can’t predict every use case – just the fact is is that scripts exist on many small and varied sites that average, non-techie site owners want to copy and paste and use without modifying php code.

            And, of course, one could add actions or filters to the theme to appropriate places in header.php to avoid the explicit proposed requirement, and offer a recommended companion plugin to do that (which is of course what I will do if this requirement is added), but the ability to add JavaScript music players or maps at specific places on a site (presentation of that content in appropriate spots) does seem like something a theme should be able to offer.

            I think having to “sneak” around the content/presentation issue, in this case presentation of content in site locations unavailable via plugins – e.g. header.php, is something that by reality is only available to the theme. No one else can affect just what comes out in the HEAD section, or the header/menu section typically found at the top of themes.

            And such specialized plugins can be confusing to the user – it has to be very theme specific. Moving stuff that can only be handled by the theme (header.php) into a fake-out companion plugin seems a little intellectually dishonest – no matter what the intent.

            And of course, I believe we owe it to the average WordPress user to offer options that are accessible to anyone – not just techies who know how to write code, or modify theme php files. The platform has moved beyond the days that only the informed elite can create custom sites.

            • Konstantin Kovshenin 9:17 pm on February 17, 2014 Permalink

              To use this new feature, you have add the script source somewhere – by lets say in the HEAD block. So my theme has an option “Add to HEAD Section”. The user copy/pastes the block right in there. (or the footer if it should be at the end.)

              Sorry but I just don’t get it :) That’s exactly what the wp_head action does. It’s meant to output stuff in the head section of your theme. Or any other theme for that matter.

              A plugin could enqueue the script, but plugins don’t keep up with all the sites that do offer such scripts.

              A plugin can also create an “Add to HEAD section” which would function exactly the same as your theme – it would output custom javascript in the HEAD section of the site.

              Maybe this is just a bad use case…

            • Chip Bennett 1:53 pm on February 18, 2014 Permalink

              First, that script doesn’t belong in the *Theme*. It is by-definition Plugin territory. The user would presumably want to retain that great-maps-startup.com functionality/integration regardless of active Theme.

              Second: two simple solutions already exist to incorporate such a script properly by the end user – Child Themes and Site Functionality Plugins.

              Third: the appropriate way for Themes to support arbitrary injection of user code at defined template locations is via defined custom template hooks (such as the Theme Hooks Alliance is trying to standardize). Offering a companion Plugin is a perfect solution, and not some sort of “loophole” or “workaround”. Heck, I do this: I define action/filter hooks in Oenology, and have an Oenology Hooks Plugin to facilitate users hooking into the template.

              Fourth: you’re simply wrong about document head output. We require the wp_head() call to come immediately before the closing HTML HEAD tag for this very reason: to ensure that Plugins and the end user can have precise control over the order that scripts and stylesheets output in the document head. Nothing can bypass the wp_head priorities by injecting something after the wp_head() call in the document head.

              Finally: I believe in focusing efforts on teaching end users the proper and safe way to administer their sites, rather than providing inherently unsafe hand-holding features. Teach users how to use a Child Theme. Teach users how to write a simple site-functionality Plugin. Don’t facilitate unsafe practices.

      • Ulrich 7:00 am on February 18, 2014 Permalink

        You could add support for the Theme Hook Alliance
        https://github.com/zamoose/themehookalliance

        You could then create a plugin that allows people to insert HTML in those separate locations. That plugin would then be compatible with any theme that uses the Theme Hook Alliance.

        I think you need to make the difference between HTML and JS scripts.

      • Chip Bennett 1:43 pm on February 18, 2014 Permalink

        Use case, please? I simply don’t understand the issue you’re trying to describe. “Arbitrary” scripts are scripts added by *users*, over which the Theme has no control. (That’s why they’re *arbitrary*.)

        If a Theme uses a script, it can simply bundle it, and enqueue it via appropriate hook (wp_enqueue_scripts, wp_head, wp_footer, etc.). This guideline has zero impact on a Theme’s ability to incorporate and to use a bundled script.

        • wpweaver 6:21 pm on February 18, 2014 Permalink

          Chip said: “Teach users how to write a simple site-functionality Plugin. Don’t facilitate unsafe practices.”

          This is an elitist and egotistical comment, and demonstrates what I think is a “we know better than you” attitude common among many WP developers. Who are the users? Not the WP core development team. Not plugin writers, not theme writers. The users are the thousands of individuals who plug along the best they can with their own sites, slowly becoming more competent every day. They are the thousands of independent SITE developers who eek out a living building WP based web sites for many others.

          These people can’t “write a simple site-functionality” plugin. A child theme – seriously? But they do have an artistic eye, and with the right tools, can build pretty amazingly functional sites. Saying they aren’t good enough to do that because they don’t have the skills to write a plugin is just a bit too much for my ethics.

          And these people are artistic perfectionists. They know how to go to Google and use the webmaster tools there to generate a perfect Google map JS snippet they would like to insert in the site content header – things that no plugin can do. The want to EASILY, without writing their own plugin (because the can’t) insert a little script to tweak some styling. They want to use some custom JavaScript available for some obscure site to add something to the header or footer. Want to see some real life use cases: Look at this discussion: http://forum.weavertheme.com/discussion/8149/poll-do-you-add-javascript-to-your-site-using-head-section-or-other-html-insertion-options

          All your use case confusion seem to miss the fact that there are tons of little content JavaScripts that add content, and that aren’t/can’t be supported by a plugin.

          Using wp_head allows the right before the closing HEAD tag, but virtually every header.php file then goes on to define the header content (like the header iamge) as well – ain’t no filter gonna fix that. Let’s see – Twenty-XXX, Oenology, … – I couldn’t find a theme that doesn’t do that, actually.

          And, as one last bit of evidence of the folly of banning script insertion from header.php and footer.php, currently anyone one with unfiltered_html capability can insert whatever they want into a plain old Text Widget. What is the difference?

          MAYBE, if there is some day a great theme hook for inserting content in then banning script insertion from header.php and footer.php might make sense, but asking the average designer to write code? Elitist in the extreme. Right now there are plenty of great reasons that a web designer with limited programming skills will want to insert a script in the code generated by header.php and footer.php, but there are no API tools to support that unless a theme does it directly.

          But I guess all these people aren’t good enough because they aren’t real programmers?

          • Chip Bennett 8:31 pm on February 18, 2014 Permalink

            Guidelines don’t impact users; they impact Theme developers. Users can inject whatever code they want, anywhere they want, in whatever template files they want. Nothing here would prevent them from doing that.

            I fail to see how a statement that espouses a belief that end users are fully capable of understanding how to use a Child Theme or a site functionality Plugin is somehow egotistical or elitist. I think it is far more elitist to assert that end users are *not* capable of understanding or learning how to use Child Themes or site functionality Plugins, for example:

            These people can’t “write a simple site-functionality” plugin. A child theme – seriously?

            Personally, I’ll keep on believing that users are fully capable of using a Child Theme, or learning how to write a site functionality Plugin. Maybe we just need to be better teachers? Maybe we need to take the time to teach the *right* way to do things, instead of encouraging lazy and unsafe, blind copy-and-paste code usage?

            Users who need to inject such arbitrary scripts at precise locations in the Theme template can and should use a Child Theme to do so. It’s not even feasible for a Theme to account for every possible template location at which a user might need/want to add some code or script. The closest we get to that is a standardized set of template action hooks, such as Theme Hooks Alliance – and even then, the correct implementation is a hook callback via Child Theme or site functionality Plugin. Exposing Theme options to that effect represents a significant security vulnerability. Doing so also represents Theme lock-in, by placing user-generated content in a Theme option; if the Theme goes, so too goes the user-generated content.

            Using wp_head allows the right before the closing HEAD tag, but virtually every header.php file then goes on to define the header content (like the header iamge) as well – ain’t no filter gonna fix that. Let’s see – Twenty-XXX, Oenology, … – I couldn’t find a theme that doesn’t do that, actually.

            Actually, Oenology makes extensive use of custom filter and action hooks, including the ability to override the site header (image/text) completely. Several other Themes do likewise, including every Theme that implements the THA standard.

            All your use case confusion seem to miss the fact that there are tons of little content JavaScripts that add content, and that aren’t/can’t be supported by a plugin.

            There are Plugins that allow insertion of arbitrary scripts in post-content, via shortcode, which is the correct implementation. Themes don’t need to be involved in post-content javascript.

            And, as one last bit of evidence of the folly of banning script insertion from header.php and footer.php…

            Part of the issue here is that you’re conflating two entirely separate issues: insertion of scripts via wp_head and wp_footer, and insertion of content in arbitrary template locations.

            The vast majority of impact of this Guideline will be on scripts hooked into wp_head and wp_footer. There’s absolutely nothing “Theme-specific” about those hooks; they are standard, universal template hooks found in every WordPress Theme worth using. A Site Functionality Plugin (or Child Theme functions.php callback) is the correct way for the user to hook arbitrary scripts into wp_head and wp_footer. Not Theme Options. Looking at your poll/forum post: if you’re encouraging your users to add Google Analytics, Facebook Like scripts, etc. via your Theme options, then you’re doing your users a disservice.

            • wpweaver 11:12 pm on February 18, 2014 Permalink

              I give up. You obviously don’t see your own elitism.

              “Guidelines don’t impact users; they impact Theme developers. Users can inject whatever code they want, anywhere they want, in whatever template files they want. Nothing here would prevent them from doing that. ”

              User’s CAN NOT inject code wherever they want. In spite of how “easy” you might think PHP programming is, IT IS NOT. There are thousands and thousands of WP site designers who can figure out how to copy/paste a little JS snippet, but who just aren’t as smart as you are, and don’t find it easy to write a little plugin, or write a little child theme. So the need to be able to do that without programming is really there. Honest. There is no need to turn a site designer into a programmer. They aren’t even interested in learning to program, and why should they?

              (And on the other side, I don’t quite understand why there are so many WP folks who think that only programmers should design themes. There are some nice themes for sure, but I’ve not met that many programmers who are really good design artists. That’s why I deeply believe there should be themes with plenty of ways for non-programmers who really are design artists to build beautiful web sites without the need to learn to program.)

              I’m not encouraging or discouraging people for adding JS snippets. These people are control freaks, and can’t find a plugin that will do every single thing a particular JS API to some well-known or obscure site has to offer, but they can get the exact JS snippet to do what they want. They want to add the exact Google tracking code they want and not rely on an invisible plugin to do it – but they don’t want to write a child theme to do that. And why should they?

              So no matter if the theme has to use a back-door plugin, or THA_ or whatever, there is still content lock in to a theme. Until there is a more widely used (what was it – 6 themes listed using THA_? It is good to see Oenology is one) standard, it just seems to me it is sensible to make such insertion areas part of theme options.

              And really – this is a sincere question – what is the difference between inserting scripts in the content header, a text widget, a footer content area, or even a post? Does it really matter where the script is injected, from a security standpoint? I really don’t know how that can be true. If done via a theme injection option, or via a text widget – the site developer can actually see the scripts are there, so I can see that “hiding” it in the header is a valid reason.

              So is the real issue theme lock-in? Then let’s say that, and not hide behind security as the reason.

              I guess it is designer vs. techie, and obviously the techies are the gate keepers.

            • Chip Bennett 1:47 am on February 19, 2014 Permalink

              Sorry, still not accepting that this position is elitist. It is simply not elitist to espouse the belief that the typical end user is perfectly capable of understanding Child Themes and Site Functionality Plugins; in fact, such a belief is the polar *opposite* of elitism.

              But let me address the point of user programming skill that you keep bringing up: owning and administering a web site is not a matter of design; further, owning and administering a web site comes inherent with the responsibility to know what you’re doing. That means some basic understanding of things like web hosting, FTP, server security, and, yes: PHP (if using a PHP-based application such as WordPress). WordPress isn’t the Ron Popeil of web applications that magically turns self-hosting a website into a set-it-and-forget-it Showtime Rotisserie.

              It is bad and irresponsible of us as developers to encourage and facilitate bad practices such as “just copy and paste this code snippet”. It is good and responsible of us as developers to help educate users about the correct, safe, and future- (and theme-)proof methods of extending WordPress functionality.

              What’s so hard about teaching someone how to write a Site Functionality Plugin? Here, I’ll demonstrate:

              examplecom-site-functionality.php

              <?php
              /**
               * Plugin Name: example.com site functionality
               */
              

              All done!

              Now, how hard is it to teach someone how to add their Google Analytics script to the file?

              <?php
              /**
               * Plugin Name: example.com site functionality
               */
              
              function examplecom_google_analytics() {
                  // Code goes here
              }
              add_action( 'wp_head', 'examplecom_google_analytics' );
              

              That’s not hard – to teach, or to understand. Users can get it; we just have to put in a modicum of effort to explain why this is a better method.

              Now, let’s back this up a bit.

              First: scripts injected by the user at wp_head and wp_footer are *by definition* Plugin territory, because they are (by definition) not part of or dependent upon the Theme, and the user would want and expect those scripts to be retained when switching Themes.

              There’s really no getting around that. Google Analytics scripts and similar need to be maintained by the user, apart from the current Theme.

              Can we agree on that point, at least? That arbitrary, user-defined scripts intended to be hooked into wp_head and wp_footer don’t belong in Theme options?

    • Narga 2:29 am on February 19, 2014 Permalink

      Themes must not implement activation redirects, admin notices, or similar functionality.
      But I refer it redirecto Theme Option Customizer after actived because user can get Theme Preview and can change Theme Options

    • Frumph 4:57 pm on March 6, 2014 Permalink

      Yeah, no. -1 to the requirement of no theme redirect, as per cyberchimp and everyone else who also disagree’s. -1 to stating licenses of my own images. -1 “Themes must not save default settings to the database without explicit user action”

      These are all recommendations; should not be requirements; everything listed about in the requirements section.

      • Chip Bennett 2:51 pm on March 7, 2014 Permalink

        Can you articulate *why* you disagree with the things you list?

        Regarding redirects: there needs to be a core-defined workflow. In the meantime: Theme settings will *always* be in the same place (Dashboard -> Appearance -> Theme options (or whatever the Theme names the page) ), and we would far better serve end users by educating them about this standard location, than by allowing all manner of arbitrary workflows that will only serve to confuse users.

        Regarding licensing of your own images: that’s always been required. We’re merely specifying a standard location to provide that explicit copyright/license information. For developer-owned resources, a blanket statement is fine. You don’t have to list each image individually, or anything onerous. You simply need to state that, unless otherwise indicated, all images are copyright you, and licensed under [theme license].

        Regarding not saving default settings to the database: why do you oppose the requirement? Does it force developers to implement sane defaults so that the Theme works “out of the box” without user intervention? Yes. That’s the point. But it’s not a difficult change, at all.

        • tskk 3:00 pm on March 7, 2014 Permalink

          I have seen many reviews where reviewer doesn’t agree with statement like “unless otherwise indicated, all images are copyright you, and licensed under [theme license].”

          So if you can specify that its acceptable in the rules, it would be helpful in avoiding arguments.

          • Chip Bennett 8:49 pm on March 7, 2014 Permalink

            Why would such a statement be unacceptable, and why wasn’t it resolved in-ticket (or an admin brought into the ticket)? Of course such a statement is acceptable. The onus is on the Theme developer to ensure that it’s *true*; but assuming that it is, it is perfectly fine to make such a blanket statement.

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel