Codex

Custom Backgrounds

Languages: English • 日本語 • (Add your language)

Custom Backgrounds is a theme feature that provides for customization of the background color and image.

See also Appearance Background Screen.

Contents

Adding Theme Support

Since Version 3.4, themes need to use add_theme_support() in the functions.php file to support custom backgrounds, like so: 

add_theme_support( 'custom-background' );

Note that you can add default arguments using: 

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

Example

An example using default '#000000' background color with 'background.jpg' background image: 

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

Outcome

The purpose of this call to add_theme_support() is to enable the Custom Background screen in the administrator's Appearance menu. It also serves as a declaration that the theme has properly implemented the body_class() and wp_head() template tags to provide feature compatibility.

When the administrator sets custom values for the theme, WordPress generates an extra style sheet in-line with the HTML headers, usually right before the end of the document's HEAD element. The extra style sheet overrides the background values from the theme's style sheet.

Example output: 

<style type="text/css" id="custom-background-css">
body.custom-background { background-color: #bdd96e; }
</style>

Note that setting the default-image parameter will instantly cause that value to become the effective Custom Background, whereas setting the default-color has no effect until the administrator visits the Custom Background page. To override this default behavior, you would have to provide a replacement for the _custom_background_cb() function.

Backwards Compatibility

To add backwards compatibility for older versions, use the following code: 

global $wp_version;
if ( version_compare( $wp_version, '3.4', '>=' ) ) :
	add_theme_support( 'custom-background' ); 
else :
	add_custom_background( $args );
endif;

Resources

Related

Theme Support: add_theme_support(), remove_theme_support(), current_theme_supports()
Features: sidebar, menus, post-formats, post-thumbnails, custom-background, custom-header, automatic-feed-links, content_width, editor-style

Retrieved from "http://codex.wordpress.org/Custom_Backgrounds"

Codex Resources