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.