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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Theme customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings..

New Guidelines (REQUIRED)

  • Required HooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. and Navigation
  • Theme Features
    • If implementing a site logo, Themes are REQUIRED to provide user-configuration of the logo via the core custom headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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 filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.. (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.

#3-4, #guidelines

I’ve updated wp themes com to use WordPress…

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.

#3-4, #wp-themes-com

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 headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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.

#3-4, #custom-backgrounds, #custom-headers

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 CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. with Previewer
  • Flexible Custom HeaderHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.-test now, and keep your eye on this site, and on the Theme-Reviewers mail-list.

#3-4