Make WordPress Themes

Tagged: 3.4 Toggle Comment Threads | Keyboard Shortcuts

  • Chip Bennett 3:21 pm on May 8, 2012 Permalink | Reply
    Tags: 3.4,   

    Proposed WordPress 3.4 Guidelines Revisions 

    As we near the final release of WordPress 3.4, it is time to begin discussion and finalization of the related changes to the Theme Review Guidelines. Below are the proposed changes. Please discuss in the comments. We’ll do our best to keep this proposed list updated based on discussions in the comments.

    New WordPress 3.4 Functionality

    • Custom Headers/Backgrounds
      • New and deprecated functions are already covered by existing Guidelines. Themes may OPTIONALLY provide backward-compatibility with pre-3.4 handling of custom backgrounds and headers
    • Child Themes
      • Child Themes will formally be allowed to be submitted for inclusion in the Theme repository.
      • Child Themes are REQUIRED to use an approved Theme as a Template (i.e. as the Parent Theme)
      • Child Themes are REQUIRED to demonstrate sufficient difference from the Parent Theme to warrant inclusion
      • Stand-alone Themes are REQUIRED to provide basic Child-Theme support, including:
        • Proper use of get_template_directory()/get_template_directory_uri() vs. get_stylesheet_directory()/get_stylesheet_directory_uri()
        • Proper enqueueing of stylesheets, and proper cascading of styles, including no inline styles in the Theme template
    • Backward Compatibility
      • Backward compatibility is covered by existing Guidelines. Per existing Guidelines (2 major WP versions required/1 major WP version recommended):
        • Themes MUST NOT support backward-compatibility for more than two major WordPress versions (i.e. 3.2).
        • Themes are RECOMMENDED NOT to support backward-compatibility for more than one major WordPress version (i.e. 3.3).
    • Theme Settings and Data Security
      • Themes are RECOMMENDED to incorporate Theme options into the WordPress core Theme customizer.

    New Guidelines (REQUIRED)

    • Required Hooks and Navigation
    • Theme Features
      • If implementing a site logo, Themes are REQUIRED to provide user-configuration of the logo via the core custom header feature. (Exception: if incorporating both a site logo and custom header, the custom header is required to support the core custom header feature, and the custom logo is then required to be implemented via custom Theme option.)
    • Function Parameters, Filters, and Action Hooks
      • Themes are REQUIRED to use function parameters, filters, and action hooks where appropriate in order to modify content, rather than hard-coding:
        • wp_title: Themes are REQUIRED to modify output via wp_title filter. (Refer to Codex note.)
        • body_class()/post_class():
          • Themes are RECOMMENDED to modify output via filter
            (body_class/post_class)
          • Themes may OPTIONALLY modify output via function parameter
            (body_class( $class )/post_class( $class ))

    New Guidelines (RECOMMENDED)

    • Code Quality
    • Script Enqueueing
      • Themes are RECOMMENDED to enqueue the comment-reply script at the comment_form_before hook
        function theme_slug_enqueue_comment_reply_script() {
	if ( comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'comment_form_before', 'theme_slug_enqueue_comment_reply_script' );

    Clarifications

    Clarifications to existing guidelines being enforced:

    • Presentation vs Functionality
      • Themes are REQUIRED to function as stand-alone code. Themes may OPTIONALLY integrate support for third-party Plugins; however, Themes are REQUIRED to degrade gracefully and to function fully and properly without any such Plugins active.

    Feedback

    What else should be included? What should be revised? Let us know in the comments.

     

    • Andy Adams 4:36 pm on May 8, 2012 Permalink | Reply

      I’m not all too familiar with the .org theme repository requirements, so forgive me if I’m missing any background information. Thanks for all your work putting this together, Chip.

      The piece that I would revise would be the requirement to use the core custom header feature for logos. Many of the themes we develop use logos that don’t span the full width of the page, so it’s technically incorrect to call it a “header”. It comes down to semantics, I suppose. But I don’t like using the word “header” when it doesn’t apply.

      • Chip Bennett 4:52 pm on May 8, 2012 Permalink | Reply

        And thus, the discussion. :)

        The thought behind the requirement is two-fold: one, consistent UI is ideal for the end user, and two, with the advent of flexible headers, the core custom header feature becomes suitable for variable-sized logos.

        Personally, I think I’d rather see core implement a “site logo” option, because a site logo is Theme-independent (much like the site favicon, title, description, etc.), and then provide a way for Themes to incorporate/support that core feature.

      • Greg Priday 4:59 pm on May 8, 2012 Permalink | Reply

        3.4 gives you a lot more control over the header size. So it doesn’t need to span the full width of the page. The nice thing about using WordPress’ header functionality is that (I assume) it’ll integrate with 3.4′s theme customizer. Pretty neat.

        I agree though, I think using “headers” as logos might confuse a user. Say the user switches from one theme that uses the header as a header, to another theme that uses the header as a logo. That might not go down too well.

        Having a site logo in the core would be a great solution but for now, maybe this requirement is a bit strict – given it’s essentially a hack.

        • Chip Bennett 5:04 pm on May 8, 2012 Permalink | Reply

          Which would be easier to migrate in the future, if a “site logo” eventually becomes a core option: a core custom header theme_mod, or a custom Theme option? I don’t know; maybe either one would be equally easy, or equally difficult.

          Also, my thinking with using custom headers for the logo is that it might help differentiate the logo as a site option, rather than as a custom Theme option. But the question of end user confusion may very well be valid…

      • Devin Price 2:22 am on May 12, 2012 Permalink | Reply

        I agree. If core had a “logo” option, I would say go ahead and make it a requirement. But header implies something different.

        Also, I assume themes that already have a logo option in their theme options would be required to change it, and that could be very confusing for users who update.

    • Konstantin 4:38 pm on May 8, 2012 Permalink | Reply

      Can we drop the requirement for the following, when loading a textdomain?

      $locale = get_locale();
      $locale_file = get_template_directory() . “/languages/$locale.php”;
      if ( is_readable( $locale_file ) )
      require_once( $locale_file );

      See #20471

      In the comment-reply example, the comments_open() is not necessary (is it?), as it is called just prior to the 'comment_form_before' action.

      • Chip Bennett 4:49 pm on May 8, 2012 Permalink | Reply

        Are you referencing the right Trac ticket? At first glance, it doesn’t appear relevant to loading a textdomain.

        And you’re right: comments_open() is likely redundant in the example.

      • Michael Fields 6:31 pm on May 8, 2012 Permalink | Reply

        I spoke with Nacin regarding this over Skype and he explained that this code is not really necessary and that core would be moving away from loading .php files for i18n. It was also removed from Twenty Ten r20473, Twenty Twelve r19844. After seeing these changesets we removed it from _s as well.

      • Chip Bennett 6:57 pm on May 8, 2012 Permalink | Reply

        So, where, exactly, are we actually requiring use of that code?

      • Andrew Nacin 5:00 am on May 10, 2012 Permalink | Reply

        There’s no reason at all for this code in a theme, ever.

      • Rico Neitzel 6:34 am on June 14, 2012 Permalink | Reply

        Hey Guys,

        dropping that would be bad for some german implementations. we’re using that file to rewrite permalinks for german sites… we don’t want to use a plugin as this setting is theme related and not system wide.

        so removing that might raise an issue for us :)

        Best,
        Rico

        • Chip Bennett 12:34 pm on June 14, 2012 Permalink | Reply

          If it works for you, keep using it. What we’ve done, though, is dropped it as a requirement. Generally speaking, a Theme is only required to load_theme_textdomain().

          • Middlesister 12:52 pm on June 16, 2012 Permalink | Reply

            But if theme’s are not required to include a $locale.php, how would languages that need/utilize them be able to localize said theme properly?

            For example greek: http://themeshaper.com/forums/topic/thematic-in-greek

            What has changed that makes these files unneccessary?

            • Chip Bennett 2:00 pm on June 16, 2012 Permalink

              In most cases, load_theme_textdomain( $textdomain, get_template_directory() . '/languages' ); will suffice. Just drop the language files, named appropriately (e.g. en_US.mo and en_US.po) in the /languages sub-folder inside the Theme, and WordPress will use them.

              If you still need to use $locale.php, then feel free to do so. We’re just no longer going to require that it be used.

    • ravi 4:45 pm on May 8, 2012 Permalink | Reply

      The section on “backward compatibility” is a bit confusing (to me): 2 major WP versions REQUIRED, 1 major WP version RECOMMENDED. That seems contradictory.

      • Chip Bennett 4:50 pm on May 8, 2012 Permalink | Reply

        Themes are required NOT to provide backward compatibility beyond two major WordPress versions, and they are recommended NOT to provide backward compatibility beyond one major WordPress version. The ideal is no backward compatibility at all, but that ideal simply isn’t practical.

    • Sayontan Sinha 9:37 pm on May 8, 2012 Permalink | Reply

      So, for the inline styles, consider this scenario:
      1. Let’s say I have some widgets where the users can put in a color that they want some text to show up with in the front end.
      2. There could be several instances of this widget, each with a different ID, which is dynamically assigned at the time of rendering. In such a case how can the user input be captured as an external style?

      I believe that inline styles should be allowed in such scenarios, because you are not taking away the flexibility from a user here: in fact you are offering the user the flexibility to provide such information through the UI.

      Note that the upfront absence of the widget ID makes it almost impossible to determine this information upfront. You could, theoretically parse the array of widgets to find the ID whenever the widgets are updated, then save the information to an external stylesheet, but this is not going to provide any added flexibility, since the method of information entry itself is from the user rather than the developer.

      • Chip Bennett 9:43 pm on May 8, 2012 Permalink | Reply

        First, remember: in (almost) all cases, exceptions can be requested.

        Second: you’re talking about a Widget, not a template file.

        Third: outputting a user-defined style inline is entirely different from hard-coding inline styles. The point isn’t that there’s anything inherently wrong with inline styles, but rather that hard-coded inline styles are almost impossible to override. User-defined styles output inline don’t fall into that situation.

        I think your scenario is essentially an example of an exception that proves the rule.

    • Bruce Wampler 5:11 pm on May 9, 2012 Permalink | Reply

      I should have posted a comment from the reviewers list here, sorry…

      But as Chip just said – the guide line applies to front end template files. After re-reading the guideline, it is clear that one of the main goals is to be sure child themes can essentially override anything the need to. Just keeping that goal in mind clarifies where inline styles really matter.

      Rather than widgets, my question was about inline style in the admin side where a child is not as likely to need to override a style. My admin interface code is full of inline styles because it is just kind of difficult to create a bunch of totally arbitrary styles for the admin style sheet anyway.

    • Bruce Wampler 5:19 pm on May 9, 2012 Permalink | Reply

      Yet another point – partly because recommended often becomes required, so about this one:
      Themes are RECOMMENDED to follow the official WordPress coding standards for all PHP code.

      I have a problem, sort of. Back when I started programming, and tab was based on 8 spaces. So I’ve always programmed with tabs or tabs+4 spaces for indentation. All my files use that – with the help of my IDE (Komodo). While not trivial, it certainly is possible to transform all that to 4 space based tabs which seems to be the PHP “standard”. Same with some of the other conventions, ( space in arg lists ) for example.

      But a problem with massive reformatting like that is that it will essentially make a diff review impossible. Perhaps a solution would be to allow a “reformatting” submission that would be mostly about making the code follow the WP standards?

      • Chip Bennett 6:39 pm on May 9, 2012 Permalink | Reply

        There are certainly some who want to move in the direction of requiring WP coding standards, but I think we need to have a very long conversation before ever considering that. There are certainly a plethora of best practices in the coding/CSS coding standards, but that doesn’t mean that they should be required.

        One of the primary reasons for core to publish coding standards is to help ensure consistency among disparate patches committed by a growing number of contributors and committers. It is fairly important for the core codebase to be consistent, in order to facilitate troubleshooting, bug-fixing, and future code enhancements and changes. None of these issues apply for non-core-bundled Themes.

        We want to make the coding/CSS coding standards recommended, in order to help raise awareness of those standards among the Theme developer community. I don’t view this recommended status as an intended escalation (unlike, say, the Settings API implementation, which I would prefer very much eventually to escalate to required); rather, I view it merely as awareness and promotion of best practices.

        I think it would be in the community’s best interest to consider each specific standard on a case-by-case basis, to determine appropriateness for inclusion in the Theme Review guidelines as required, rather than a wholesale adoption of those standards. By making the standards recommended, it opens the door to such further discussions within the community.

    • Andrew Nacin 5:07 am on May 10, 2012 Permalink | Reply

      A few points:

      Both Twenty Ten and Twenty Eleven would fail a number of these guidelines, including: not enqueueing styles, not filtering wp_title(), etc. I would be happy to see a Trac ticket to change these in 3.4 or 3.5. But until we do change them, I’m weary (but okay) with making these requirements.

      The CSS guidelines are still in draft mode, and may not be finalized before 3.4′s release. They were proposed originally by the Automattic theme team and not yet endorsed by the various frontend developers working on core.

      get_template_directory_uri() versus get_stylesheet_directory_uri() is not straightforward and may be tough to judge at times.

      • Chip Bennett 5:07 pm on May 10, 2012 Permalink | Reply

        I’ll be happy to submit any necessary patches for Twenty Ten and Twenty Eleven. If you see specific places where either would fail, just ping me and I’ll write them up.

        Thanks for the caveat regarding the CSS coding standards. That’s yet another reason that nothing more than recommended is appropriate at this time.

        In some cases, get_template_directory*() vs get_stylesheet_directory*() will be a matter of intended use; most of the time, though, the correct template tag to use is fairly clear. (Can/should be overridden by a Child Theme? Use stylesheet. Can’t/shouldn’t be overridden by a Child Theme? Use template.)

        • Justin Tadlock 6:04 pm on May 10, 2012 Permalink | Reply

          The use of get_stylesheet_directory*() should rarely be used in standalone/parent themes. It makes the assumption that either a child theme is not being used or that a particular file is housed within a child theme.

          Nearly always, if a regular theme is using *stylesheet*, it should be falling back to *template*.

      • Konstantin 8:29 pm on May 10, 2012 Permalink | Reply

        Oh, I’d love to contribute too (as a matter of fact, I have a patch prepared).

        @nacin: When you say “enqueueing styles” would that also include style.css?

    • Chip Bennett 5:02 pm on May 10, 2012 Permalink | Reply

      Please note the recent addition, under Clarifications, regarding stand-alone Theme functionality, and Plugin integration. This is something the WPTRT has been enforcing all along, but is not explicitly spelled out in the current Guidelines.

    • Justin Tadlock 6:01 pm on May 10, 2012 Permalink | Reply

      Themes are RECOMMENDED to incorporate Theme options into the WordPress core Theme customizer.

      Why recommend this at all? I’m already imagining disastrous scenarios of theme authors going too far. I definitely don’t want to see themes add 100s of options to this thing.

      • Chip Bennett 6:47 pm on May 10, 2012 Permalink | Reply

        I don’t understand the hesitation. Wouldn’t initial user configuration of custom Theme options via the customizer, upon Theme activation, provide the best-possible user experience?

        Sure, we’ll need to be sensible about how that integration takes place, but I think we can safely play that by ear as developers get their feet wet with the new feature. If we take the same philosophical approach with the customizer tab as we do with the Appearance sub-menu, I think we can reasonably keep things manageable, and avoid such disastrous scenarios as you’re envisioning.

        • Justin Tadlock 12:06 am on May 11, 2012 Permalink | Reply

          It’s just a question of whether we really need to recommend it, especially until we see how theme authors are utilizing it. I’m neither for or against recommending it. I’d just like to be more cautious with it for a while.

          As far as best user experience goes, I agree, to a degree. It can make for a great user experience as well as a horrible one.

          It’s just something I thought I’d throw out there for discussion.

        • Andrew Nacin 2:35 am on May 11, 2012 Permalink | Reply

          I agree with Justin. I would not “Recommend” it yet.

          • Chip Bennett 1:42 pm on May 11, 2012 Permalink | Reply

            I can see where both of you are coming from. Maybe OPTIONAL is a better approach initially? I want the customizer feature to be in the Guidelines (as with basically every other core feature that touches or interacts with Themes), as a basis for establishing future implementation guidelines.

    • Konstantin Kovshenin 6:56 am on May 11, 2012 Permalink | Reply

      I think it’s also time to make wp_nav_menu required.

      • Chip Bennett 1:44 pm on May 11, 2012 Permalink | Reply

        well, wp_nav_menu() is required: if the Theme design incorporates a navigation menu. The line we’ve not crossed thus far is dictating Theme design or aesthetic, and I’m not sure we want to cross that line. (Bear in mind that Widget support is required, and that Nav Menu Widgets can be added to dynamic sidebars – so technically speaking, all Themes do support navigation menus, at least in some form.)

    • Konstantin 7:12 am on May 11, 2012 Permalink | Reply

      I’d love to have a clearer Credit Link guideline with less leeway for both, Theme Authors and Reviewers!

      I’m not too happy about the entire “Credit Link” section of the Theme Review codex page. And when I say not too happy, I mean I hate this part of every review, because of the enormous propability that my findings won’t correlate with the opionion of more seasoned reviewers (as it happened on this one).

      What more is there to a Theme URL, other than it being a page specifically related to the Theme?
      What is relevant and appropriate in a public-facing credit link?
      What we understand under a project/development website?

      As I said before, I think a clarification, and writing up requirements that are currently enforced but not documented, would benefit both, Theme Authors and Reviewers.

      • Chip Bennett 2:01 pm on May 11, 2012 Permalink | Reply

        I completely understand your frustration. Trying to keep credit link guidelines completely objective, while at the same time avoiding CFR-level detail and breadth, can be a delicate balance.

        Regarding the ticket you linked (and if you want to discuss that one specifically, I’d be happy to do so in-ticket), when I look at the Theme URI, especially for a site that would otherwise not be valid as Author URI, the red flag for me is the ratio of Theme-related content to non-Theme-related content. Another criterion for me is, “how beneficial is this content to the end user?” But these criteria are difficult-to-impossible to quantify objectively. Call it experience-based intuition. (Maybe call it jadedness from dealing with too many Themes with crappy credit links?)

        My personal preference/ideal for an appropriate Theme URI would be Theme-specific landing page on a Theme developer (or Theme shop) site, not an essentially orphaned page, with some Theme-related content, on a site otherwise unrelated to WordPress/Themes. But that preference is not the consensus, so we try to strike a balance regarding appropriateness.

        Theme URI is one of the most subjective guidelines, and as such ends up causing most of the headaches regarding Theme-review observations.

        • Konstantin 3:13 pm on May 11, 2012 Permalink | Reply

          Please do share your thoughts in-ticket!

          I can see how it is difficult to to come up with objective guidelines, given the variations in Theme URL pages. This is probably why they haven’t been defined in more detail yet.

          But how about starting with someting like:

          Theme page is RECOMMENDED to be on a WordPress/Theme related site.

          I’d love to hear from other reviewers what they look for, when reviewing a Theme and it comes to the Crdit Links! Please share, so we can come to a better understanding on this.

        • Vicky Arulsingam 1:48 am on May 14, 2012 Permalink | Reply

          The key here is unrelated content.

          I’m okay with the Theme URI being an orphaned page but only if there isn’t unrelated content.

    • Clementine Hobbins 1:00 pm on May 17, 2012 Permalink | Reply

      Thx for information.

    • Satish Gandham 7:51 am on May 20, 2012 Permalink | Reply

      Can you please include guidelines for the featured themes, or at least ask the reviewer to say why he thought the theme should be featured.

    • Arie Putranto 8:31 pm on May 20, 2012 Permalink | Reply

      Well, what if comments.php does not exists but replace by a function which generated the comments list? Is it okay?

      • Justin Tadlock 11:17 pm on August 4, 2012 Permalink | Reply

        There’s technically not a need for the comments.php template. If your theme doesn’t need it but still handles comments correctly using the appropriate WordPress functions, you’ll be fine.

        • Chip Bennett 11:25 pm on August 4, 2012 Permalink | Reply

          I disagree. It is a general principle that Themes not rely on legacy template-part file support. And specifically for comments.php, according to source, backward compat for comments.php in comments_template() is intended to be removed, which IMHO is equivalent to it being considered as deprecated:


          else // Backward compat code will be removed in a future release
          919 require( ABSPATH . WPINC . '/theme-compat/comments.php');

          Thus, proper implementation of comments requires use of comments.php, included in the template via comments_template().

          If a Theme has a legitimate reason for an exception to this implementation, then that exception can be handled just like any other guideline exception.

    • @mercime 5:06 pm on May 22, 2012 Permalink | Reply

      We know now that there are theme authors who add another subpanel, Appearances > More Themes in themes that have been approved/accepted into the WP Theme Repository http://lists.wordpress.org/pipermail/theme-reviewers/2012-April/008791.html

      There should be guidelines surrounding the practice if this (More Themes subpanel) continues and grows, for example:
      1. Maximum number of themes which can be listed in that subpanel.
      2. Links from that subpanel should only go to webpages of approved Theme URL
      3. No affiliate links.
      4. In relation to that, no calling home scripts to find out how many clicked from subpanel links to theme webpage
      5. Best practices for adding subpanel.
      6. Etc.

      Thanks.

      • Konstantin Obenland 8:05 pm on May 23, 2012 Permalink | Reply

        How many Theme Authors actually do this that we can’t deal with something like this on a case-by-case basis?

    • Emil Uzelac 5:36 am on June 22, 2012 Permalink | Reply

      Just a very quick note that this 3.4 guidelines will need to be discussed bit more before we actually decide on anything and push this over to http://codex.wordpress.org/Theme_Review

      For example get_template_directory()/get_template_directory_uri() should be recommended, not required.

      The reason is that many users already have Child Themes in place with non get_template_directory()/get_template_directory_uri(), requiring Themes to make a switch will break all of them. If requirements are needed, let’s set this for new submissions only, while only recommending to currently approved ones.

      Yes, this is definitely way to go, but not for currently approved Themes.

      Thanks,
      Emil

      • Justin Tadlock 8:34 am on June 24, 2012 Permalink | Reply

        Properly using get_template_directory() and get_template_directory_uri() is already required. From the guidelines:

        All template tags and hooks used in a Theme are required to be implemented properly.

  • Andrew Nacin 4:29 pm on April 23, 2012 Permalink | Reply
    Tags: 3.4, wp-themes.com   

    I’ve updated wp-themes.com to use WordPress 3.4, that way I could fix #WP20514. This could potentially reveal themes that are broken in 3.4, so keep an eye out. I will be watching the error logs.

     

  • Chip Bennett 2:58 pm on April 6, 2012 Permalink | Reply
    Tags: 3.4, custom backgrounds, custom headers   

    Updating Custom Backgrounds and Custom Headers for WordPress 3.4 

    When WordPress 3.4 is released, the old implementation methods for custom backgrounds and custom image headers via add_custom_background() and add_custom_image_header() will be deprecated, in favor of a much simpler – and much more powerful – implementation method, using add_theme_support(). Here’s how to update your existing Themes to use the new implementation.

    Custom Backgrounds

    Old method:

    add_custom_background();

    New method:

    add_theme_support( 'custom-background' );

    (Admit it: that was easy, wasn’t it?)

    Now for the fun part: add_theme_support( 'custom-background', $args ). What’s that: $args, you say? Yes! This method accepts an arguments array. Here are the defaults:

    $defaults = array( 
	'default-image' => '',
	'default-color' => '',
	'wp-head-callback' => '_custom_background_cb',
	'admin-head-callback' => '',
	'admin-preview-callback' => ''
)

    Defining a default background image or default background color just became dead-simple:

    add_theme_support( 'custom-background', array(
	// Background color default
	'default-color' => '000',
	// Background image default
	'default-image' => get_template_directory_uri() . '/images/background.jpg'
) );

    You may notice that the arguments array also includes the same callbacks that have always been available for custom image header implementation, so you also have more control over the front-end style definitions as well as the admin display.

    Custom Headers

    Old method:

    // Define default header image constant
define( 'HEADER_IMAGE', get_template_directory_uri() . '/images/headers/default.jpg' );
// Define header image width constant
define( 'HEADER_IMAGE_WIDTH', 1000 );
// Define header image height constant
define( 'HEADER_IMAGE_HEIGHT', 198 );
// Define header text constant
define( 'NO_HEADER_TEXT', false );
// Define header text color constant
define( 'HEADER_TEXTCOLOR', '000' );
// Turn on random header image rotation by default.
// Requires HEADER_IMAGE to be null
add_theme_support( 'custom-header', array( 'random-default' => true ) );

// Add Theme support
add_custom_image_header( $wphead_cb, $adminhead_cb, $adminpreview_cb );

    New method:

    add_theme_support( 'custom-header', array(
	// Header image default
	'default-image'			=> get_template_directory_uri() . '/images/headers/default.jpg',
	// Header text display default
	'header-text'			=> false,
	// Header text color default
	'default-text-color'		=> '000',
	// Header image width (in pixels)
	'width'				=> 1000,
	// Header image height (in pixels)
	'height'			=> 198,
	// Header image random rotation default
	'random-default'		=> false,
	// Template header style callback
	'wp-head-callback'		=> $wphead_cb,
	// Admin header style callback
	'admin-head-callback'		=> $adminhead_cb,
	// Admin preview style callback
	'admin-preview-callback'	=> $adminpreview_cb
) );

    Again: that was easy, wasn’t it?

    Just to clarify, here are the old-constant/new-array-key equivalents:

    HEADER_IMAGE		=> 'default-image'
HEADER_IMAGE_WIDTH	=> 'width'
HEADER_IMAGE_HEIGHT	=> 'height'
NO_HEADER_TEXT		=> 'header-text'
HEADER_TEXTCOLOR	=> 'default-text-color'

    All of the same callbacks are supported, exactly as before.

    For reference, here is the complete defaults array:

    $defaults = array(
	'default-image' => '',
	'random-default' => false,
	'width' => 0,
	'height' => 0,
	'flex-height' => false,
	'flex-width' => false,
	'default-text-color' => '',
	'header-text' => true,
	'uploads' => true,
	'wp-head-callback' => '',
	'admin-head-callback' => '',
	'admin-preview-callback' => '',
);

    As you can see from the defaults array, this new implementation adds some new functionality: flexible headers. See Amy Hendrix’s excellent write-up for more information on this feature.

     

    • Ryan Hellyer 7:49 pm on April 6, 2012 Permalink | Reply

      Looks slick! Thanks for the run down on how it works Chip.

    • Emil Uzelac 9:28 pm on April 6, 2012 Permalink | Reply

      Bravo Chip!

    • Piet 2:28 am on April 7, 2012 Permalink | Reply

      Excellent information, thanks Chip!

      Do you also know what exactly the function is of the last 3 arguments (‘wp-head-callback’ => ‘_custom_background_cb’, ‘admin-head-callback’ => ” and ‘admin-preview-callback’ => ”) of the custom-background?
      The reason I ask is because I have been trying to add some text to the upload custom background screen, but haven’t figured out how to do that yet. Would be great if you can explain/show how that too.

      Cheers,
      Piet

      • Creative Media + 7:02 pm on April 7, 2012 Permalink | Reply

        Good question. I have been wondering about the same exact thing!

        How can that be done? Thx much

      • Chip Bennett 6:11 pm on April 8, 2012 Permalink | Reply

        These callbacks *should* work the same as with the custom header feature. I’m hoping to have time to write a more in-depth tutorial later, going into full details. But for the time being, have a look at Twenty Eleven. The current version implements all three callbacks.

    • Rilwis 2:21 pm on April 7, 2012 Permalink | Reply

      Great! Thanks for letting us know about these cool updates.

    • Flick 4:31 am on April 8, 2012 Permalink | Reply

      Looks like a great new feature! Am conscious of the fact that TwentyTen, for instance, uses the custom header feature – will it be updated for 3.4? Thanks

      • Chip Bennett 6:12 pm on April 8, 2012 Permalink | Reply

        I believe Twenty Eleven already has been updated (in trunk). I’m not sure about Twenty Ten. I would guess that it will be, but I really don’t know.

    • Michael 10:15 am on April 10, 2012 Permalink | Reply

      If I use the new methods in my themes this will not work in WP versions prior to 3.4 of course. is there an easy fallback? Or the other way around. How long can I still use the old methods? Any ideas?

      Cheers
      Michael

      • Chip Bennett 1:48 pm on April 10, 2012 Permalink | Reply

        We’ll discuss specifics as we start to formalize the guidelines revisions for the 3.4 update; however, some form of backward compatibility will certainly be allowed. Our current practice is: 1) no deprecated function calls, and 2) no backward compatibility beyond one prior major release. So, I imagine we’ll end up with Themes being required to use the new implementation, but also being able to provide back-compat for 3.3 users (via version check, or function_exists() check, etc.). I’ll have to go back to see how we handled the deprecation/change to contextual help in 3.3, since it is a nearly identical situation.

      • Michael Fields 4:37 pm on April 16, 2012 Permalink | Reply

        P2 version 1.4.0 has a neat way to deal with backward compatibility. You can browse the code here: http://themes.svn.wordpress.org/p2/1.4.0/inc/custom-header.php

    • Silke 6:38 pm on April 16, 2012 Permalink | Reply

      Hi there, is there any css way to style that uploaded custom-background image? I found the WP.org text about body class, but I am not sure, if that is the answer and how to make ist work…

      Thanks

    • Qamar 11:57 am on April 18, 2012 Permalink | Reply

      Thanks a lot for the update.

    • winsorcm 4:28 am on June 5, 2012 Permalink | Reply

      Hi there. I have never touched the functions.php file but here is what i’d like to do:

      • In the TwentyTen theme, there is a “Background” tab under Appearance that allows you to set the background of the whole page.
      • I would like to use this same tab, but rather than set the background of the whole page, I want to set the background of a particular div.
      • Is it simple enough to just tell WordPress where to put the background image?

      Thank you!

    • Maor Chasen 6:55 pm on June 13, 2012 Permalink | Reply

      This is an amazing improvement! Thanks for the short guide, Chip!

    • Michelle 8:55 pm on June 13, 2012 Permalink | Reply

      Thank you!! Amazing timing, I was just about to go figure out how to do this in 3.3.2 – yay WordPress developers and thank so much for the explanation!

    • Richard 12:28 pm on June 14, 2012 Permalink | Reply

      Any idea why trying to show the default image like so doesn’t work?

      echo ‘default-image;
      echo’” width=”100%” alt=”Header Image” />’;

      • Chip Bennett 12:41 pm on June 14, 2012 Permalink | Reply

        You might try asking on the theme-reviewers mail-list, or in this case, the wordpress.org support forums, for this type of question.

    • Richard 12:30 pm on June 14, 2012 Permalink | Reply

      Damn.

      Bet this doesn’t work either.

      get_custom_header()->default-image

      • Chip Bennett 9:53 pm on June 14, 2012 Permalink | Reply

        If I’m reading source correctly, this should work:

        $custom_header_args = get_theme_support( ‘custom-header’ );
        $defaultimage = $custom_header_args['default-image'];

    • OffCourse2010 5:34 pm on June 19, 2012 Permalink | Reply

      Hi

      For a theme I used the previous code which included some examples for the header that the user could choose from start. Is there a way to do something similar with backgrounds, to allow, for example to have a paper, wood, metal, etc texture to choose from?

      Thank you

    • surowski 8:11 pm on February 3, 2013 Permalink | Reply

      hi mate, what about a transparent (or semi-transparent) background on one of the subpages
      (not to change the main background, but only one of the sub-pages – to semi-transparent. that the main background would be visible) ? is there a solution?

    • Rob 7:35 pm on February 19, 2013 Permalink | Reply

      Hi and thanks for the great article. I just started with WordPress a few days ago (normly I am a Joomla guy) and I am sorting out how to add options to the theme I just created.

      This is just a great option. But I would like to know, if it is possible to change only the background colors without offering the option to add a background image?

      Thanks in advance for the support.

      Best regards from Berlin (Germany),

      Rob van Linda

      • Chip Bennett 4:22 pm on February 26, 2013 Permalink | Reply

        Rob,

        This is certainly possible, but a Theme that did so would not be accepted for inclusion in the official Theme directory.

  • Chip Bennett 1:24 pm on April 5, 2012 Permalink | Reply
    Tags: 3.4   

    Heads Up To Developers: WordPress 3.4 is in Beta 

    See the post on the wpdevel site:

     Here’s some of what’s new:

    • Theme Customizer with Previewer
    • Flexible Custom Header Sizes
    • Selecting Custom Header and Background Images from Media Library
    • Better experience searching for and choosing a theme

    And some of the under-the-hood changes:

    • New XML-RPC API for external and mobile applications
    • New API for registering theme support for custom headers and backgrounds
    • Performance improvements to WP_Query by splitting the query (Please test!)
    • Internationalization improvements (improved performance and locale support)
    • Performance and API improvements when working with lists of installed themes
    • Support for installing child themes from the WordPress Themes Directory

    Note: there are changes in WordPress 3.4 that will impact Themes, and the Theme Review guidelines. Now is the time to switch your development environments over to the beta version, and start hammering on the changes. (And if you find any bugs, report them!) Soon, the Theme Review Team will begin discussions regarding changes to the Guidelines. If you are interested in participating in those discussions, please beta-test now, and keep your eye on this site, and on the Theme-Reviewers mail-list.

     

    • tislam100 1:28 pm on April 5, 2012 Permalink | Reply

      how does the “Theme Customizer” work?

      • Chip Bennett 1:33 pm on April 5, 2012 Permalink | Reply

        Install it and see. :)

        Basically, it is a rewrite of the “Dashboard -> Appearance” sub-menu pages UI, as a “panel” instead of as discrete sub-menu pages.

    • tislam100 3:03 pm on April 5, 2012 Permalink | Reply

      cool!! :)

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