Adding a custom header image to your WordPress theme
Every new iteration of WordPress (version 3.0.1 at the time of writing) brings a host of new features and bug fixes. One feature that I completely missed in 3.0 was the new custom header functionality. Before 3.0 it would be a case of hacking together your own solution using custom fields or using a separate plug-in. Thankfully the WordPress team have added this functionality directly to the core.
It just so happens that I’ve had a request for a customisable header image on an future project, so decided to have a play and see how difficult it is to implement. Well it isn’t difficult at all, very simple in fact.
First you will need to edit your functions.php located in your theme directory. Go ahead and create one if it isn’t in the directory. Now copy and paste the code below into the file. I’ve commented the code but it’s all quite self explanatory. Change the height and width of the image and change the directories where needed.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<?php
//Check see if the customisetheme_setup exists
if ( !function_exists('customisetheme_setup') ):
//Any theme customisations contained in this function
function customisetheme_setup() {
//Define default header image
define( 'HEADER_IMAGE', '%s/header/default.jpg' );
//Define the width and height of our header image
define( 'HEADER_IMAGE_WIDTH', apply_filters( 'customisetheme_header_image_width', 960 ) );
define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'customisetheme_header_image_height', 220 ) );
//Turn off text inside the header image
define( 'NO_HEADER_TEXT', true );
//Don't forget this, it adds the functionality to the admin menu
add_custom_image_header( '', 'customisetheme_admin_header_style' );
//Set some custom header images, add as many as you like
//%s is a placeholder for your theme directory
$customHeaders = array (
//Image 1
'perfectbeach' => array (
'url' => '%s/header/default.jpg',
'thumbnail_url' => '%s/header/thumbnails/pb-thumbnail.jpg',
'description' => __( 'Perfect Beach', 'customisetheme' )
),
//Image 2
'tiger' => array (
'url' => '%s/header/tiger.jpg',
'thumbnail_url' => '%s/header/thumbnails/tiger-thumbnail.jpg',
'description' => __( 'Tiger', 'customisetheme' )
),
//Image 3
'lunar' => array (
'url' => '%s/header/lunar.jpg',
'thumbnail_url' => '%s/header/thumbnails/lunar-thumbnail.jpg',
'description' => __( 'Lunar', 'customisetheme' )
)
);
//Register the images with Wordpress
register_default_headers($customHeaders);
}
endif;
if ( ! function_exists( 'customisetheme_admin_header_style' ) ) :
//Function fired and inline styles added to the admin panel
//Customise as required
function customisetheme_admin_header_style() {
?>
<style type="text/css">
#wpbody-content #headimg {
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
border: 1px solid #333;
}
</style>
<?php
}
endif;
//Execute our custom theme functionality
add_action( 'after_setup_theme', 'customisetheme_setup' );
?>
By adding the code above you will now see a new option under “Appearance” in the admin panel called “Header”. From there you should be able to see all the images and options we just set in the functions.php file. The only thing left to do now is add the header image to the theme.
Where you place the following code will be depend on your theme setup; I’ve decided to place it in the header.php file as I want the image to appear on every page. You may only want the image to appear on specific templates e.g. pages, archive, category (you could also use WordPress conditional tags to do this).
1
2
3
4
5
6
<div id="header">
<!-- other header code here.... -->
<!-- This line adds the header to the theme -->
<img id="headerimg" src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="Header image alt text" />
</div>
And there you have it, one header image that you can customise via the WordPress admin panel. An ID is attached to the image for CSS styling where needed.
The example above is quite a simplified version of the header image functionality. It is possible to place text over the image and even have a different image per blog post by using the custom thumbnail functionality, but these are beyond the scope of this blog post. Copy & paste and enjoy!
