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
  • Add to list of template tags REQUIRED where appropriate: previous_image_link()/next_image_link() (or equivalent)
• 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
  • Themes are RECOMMENDED to follow the official WordPress coding standards for all PHP code.
  • Themes are RECOMMENDED to follow the official WordPress CSS coding standards for all CSS.
• 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.

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.

 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.