How to Enable Custom Header Images Panel in WordPress 3.0

If you guys haven’t had a chance to test out WordPress 3.0, then you are missing out. We have created numerous posts about WordPress 3.0 features and have shown WordPress 3.0 screenshots as well. One of the note-worthy upgrade in this version is a new default theme called Twenty Ten. This theme has a lot of great features enabled, but one of the features that a lot of users want is the Custom Headers Panel. In this article, we will share with you how you can enable custom headers with a back-end admin panel in WordPress 3.0.

What exactly will this feature do?

It will create a tab in your admin panel which will allow you to change header images. You can register default images if you are a theme designer to give users more options. It also allows users to upload custom images for the header. Last but certainly not the least, this feature utilizes post thumbnails on single post pages. If your post thumbnail is big enough to fit the header size, then it will use your post thumbnail as the header instead of the default image. If your thumbnail is bigger, then it will crop it down for you.

Watch the Screencast

How to Add this?

We took the code straight from Twenty Ten’s functions.php file. You need to paste the following codes in your theme’s functions.php file.

<?php
/** Tell WordPress to run yourtheme_setup() when the 'after_setup_theme' hook is run. */
add_action( 'after_setup_theme', 'yourtheme_setup' );

if ( ! function_exists('yourtheme_setup') ):
/**
* @uses add_custom_image_header() To add support for a custom header.
* @uses register_default_headers() To register the default custom header images provided with the theme.
*
* @since 3.0.0
*/
function yourtheme_setup() {

// This theme uses post thumbnails
add_theme_support( 'post-thumbnails' );

// Your changeable header business starts here
define( 'HEADER_TEXTCOLOR', '' );
// No CSS, just IMG call. The %s is a placeholder for the theme template directory URI.
define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' );

// The height and width of your custom header. You can hook into the theme's own filters to change these values.
// Add a filter to yourtheme_header_image_width and yourtheme_header_image_height to change these values.
define( 'HEADER_IMAGE_WIDTH', apply_filters( 'yourtheme_header_image_width', 940 ) );
define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'yourtheme_header_image_height', 198 ) );

// We'll be using post thumbnails for custom header images on posts and pages.
// We want them to be 940 pixels wide by 198 pixels tall (larger images will be auto-cropped to fit).
set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true );

// Don't support text inside the header image.
define( 'NO_HEADER_TEXT', true );

// Add a way for the custom header to be styled in the admin panel that controls
// custom headers. See yourtheme_admin_header_style(), below.
add_custom_image_header( '', 'yourtheme_admin_header_style' );

// … and thus ends the changeable header business.

// Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI.
register_default_headers( array (
'berries' => array (
'url' => '%s/images/headers/berries.jpg',
'thumbnail_url' => '%s/images/headers/berries-thumbnail.jpg',
'description' => __( 'Berries', 'yourtheme' )
),
'cherryblossom' => array (
'url' => '%s/images/headers/cherryblossoms.jpg',
'thumbnail_url' => '%s/images/headers/cherryblossoms-thumbnail.jpg',
'description' => __( 'Cherry Blossoms', 'yourtheme' )
),
'concave' => array (
'url' => '%s/images/headers/concave.jpg',
'thumbnail_url' => '%s/images/headers/concave-thumbnail.jpg',
'description' => __( 'Concave', 'yourtheme' )
),
'fern' => array (
'url' => '%s/images/headers/fern.jpg',
'thumbnail_url' => '%s/images/headers/fern-thumbnail.jpg',
'description' => __( 'Fern', 'yourtheme' )
),
'forestfloor' => array (
'url' => '%s/images/headers/forestfloor.jpg',
'thumbnail_url' => '%s/images/headers/forestfloor-thumbnail.jpg',
'description' => __( 'Forest Floor', 'yourtheme' )
),
'inkwell' => array (
'url' => '%s/images/headers/inkwell.jpg',
'thumbnail_url' => '%s/images/headers/inkwell-thumbnail.jpg',
'description' => __( 'Inkwell', 'yourtheme' )
),
'path' => array (
'url' => '%s/images/headers/path.jpg',
'thumbnail_url' => '%s/images/headers/path-thumbnail.jpg',
'description' => __( 'Path', 'yourtheme' )
),
'sunset' => array (
'url' => '%s/images/headers/sunset.jpg',
'thumbnail_url' => '%s/images/headers/sunset-thumbnail.jpg',
'description' => __( 'Sunset', 'yourtheme' )
)
) );
}
endif;

if ( ! function_exists( 'yourtheme_admin_header_style' ) ) :
/**
* Styles the header image displayed on the Appearance > Header admin panel.
*
* Referenced via add_custom_image_header() in yourtheme_setup().
*
* @since 3.0.0
*/
function yourtheme_admin_header_style() {
?>
<style type="text/css">
#headimg {
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
}
#headimg h1, #headimg #desc {
display: none;
}
</style>
<?php
}
endif;
?>

That is jibbrish to me. Please Explain

Ofcourse, this might look jibrish to some of you. This is mostly for theme designers, but we will do our best to break it down. Before we start make sure you copy and paste this code in your code editor, so you can make the changes necessary.

Note: We are using /images/headers/ as the directory where you will store your default header images.

• You start the code out by creating a function yourtheme_setup().
• In line 21, we define the default header image. Note there is a variable %s which is basically a placeholder for the theme directory URI.
• Line 25 and 26 is where you define the image width and height. By default it is set to 940px wide and 198px high. You can change it by editing those two lines.
• Starting from line 42, we start registering the default headers. These are the images that will show up as a radio button option in your admin panel. If you need more options then simply follow the format being used.
• In line 95, we choose the header styling. You do not need to change these settings because you alreadyd efined them in Line 25 and 26.

That is all what you are doing for the theme’s functions.php file. Next we are going to go into how you are going to add this to your theme.

Code to add in your Theme

This code will most likely go in the theme’s header.php file. You can style it however you like.

<?php
// Check if this is a post or page, if it has a thumbnail, and if it's a big one
if ( is_singular() &&
has_post_thumbnail( $post->ID ) &&
( /* $src, $width, $height */ $image = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'post-thumbnail') ) &&
$image[1] >= HEADER_IMAGE_WIDTH ) :
// We have a new header image!
echo get_the_post_thumbnail( $post->ID, 'post-thumbnail' );
else : ?>
<img src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="" />
<?php endif; ?>

What is this code doing?

• First, it is checking if it is a single post or a page. It also checks if this post/page has a thumbnail, and whether it is big enough.
• If the page is a single page and has a big enough thumbnail, then it displays the post thumbnail specific for that post.
• If it is not a single page, or the post thumbnail is not big enough, then it will show the default header.

We hope this tutorial was helpful. We got a few emails asking about this tutorial, so we broke the code down from the Twenty Ten theme. If you have any questions, then feel free to ask in the comments.