How To: Custom Headers in WordPress Themes
We all love WordPress. It’s streets ahead of its rivals in the blogging platform stakes and with good reason. While some of its competitors fumbled around trying to create a business model that allowed them to charge for releases (only to have to revert back to “open source”, tail between their legs), the WordPress folk just got on with improving the platform and building an active community of users and contributors. One of the strengths of WordPress is the ease with which themes can be developed. The so called Template Tags give theme authors access to a wide array of data deep within WordPress, safe in the knowledge that they aren’t accessing the database directly.
In addition to the Template Tags, there are also some nice little extras. One of which is the ability add custom headers to your theme. This really comes into its own when you are considering releasing a theme out into the wider world. It gives users of your theme a really simple way to add custom images to their header and crop them appropriately, all through a nice, usable, front end. While this functionality has been around for a while, since at least version 2.1, it’s not terribly well documented. So I’ve knocked up this quick guide to using custom headers in WordPress themes. If you’ve got any questions or improvement, please drop them in the comments.
The Basics
The general approach to custom headers assumes that there’s a space in your template that contains a header. And this space can be styled fairly specifically through css. To show you what I mean by this, I’ve copied out a very simple theme page below. This includes space for a header which can easily be styled through CSS thanks to the use of a div with the id of “header”.
<?php wp_head(); ?> <html> <head> <link rel="stylesheet" href="
<?php bloginfo('template_url'); ?>
/style.css" type="text/css" media="screen, projection" />
<title>Blog Title</title>
</head>
<body>
<div id="header">
<h1><a href="#"><?php bloginfo('title'); ?></a></h1>
<p id="desc"><?php bloginfo('description'); ?></p>
</div><!-- End #header -->
</body>
</html>
As you can see, the basics of a template file. What the custom header will do is hijack the CSS that controls the heading. Essentially it will do two things. Firstly is can apply a background image to the div, and secondly it can control the color and visibility of the text that appears in the div. These options will appear in a new “Header Image and Color” area in the WordPress admin in the Presentation (Design in version 2.5) area.
The Mechanics
As you can image, writing the code for uploading and cropping images isn’t straight forward. Thankfully all the hard work is handled by the WordPress API. All we have to do is make sure our theme supports it. We’ve already covered the part of our theme that allows all the magic to happen, but how about the admin options? How do we make those available?
As with other theme related options, the calls to the WordPress API happen in your functions.php file. It’s all really simple. First of all we define some default styles for our heading area. Then we write two pieces of CSS. One that styles the header in the blog, and one that styles the header in the admin interface. This CSS has to be written such that it can be dropped straight into the HEAD area of your template, so make sure it’s wrapped in appropriate STYLE tags.
These style snippets need to be assigned to two separate functions. The functions don’t need to so anything other than output the style snippets, but you can include PHP code within them, so feel free to go mad with as much convoluted logic as you see fit. A few things you must do, however, is to set the background-image to be “header_image()” and set the dimensions to be the same as your defaults. You should also check to make sure you hide text if that option is chosen (display: none) and set the color to any chosen by the user. You also need to be aware that while you can choose your classes and ids in the theme, you have to use the ids “headimg” and “desc” for the admin style. “headimg” is the surrounding div while “desc” is the id of a div that contains the site’s description.
These two functions are then called in the add_custom_image_header function, which is the key to accessing the custom header API. If this all sounds a bit complicated, I’ve included a simple implementation below which should point you in the right direction. I’ve commented it as much as possible.
<?php
// Set some default values
define('HEADER_TEXTCOLOR', 'fff'); // Default text color
define('HEADER_IMAGE', '%s/default.jpg'); // %s is theme dir uri, set a default image
define('HEADER_IMAGE_WIDTH', 500); // Default image width is actually the div's height
define('HEADER_IMAGE_HEIGHT', 150); // Same for height
function header_style() {
// This function defines the style for the theme
// You can change these selectors to match your theme
?>
<style type="text/css">
#header{
background: url(<?php header_image() ?>) no-repeat;
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width:<?php echo HEADER_IMAGE_WIDTH; ?>px;
padding:0 0 0 18px;
font-family: Arial;
}
#header h1 {
padding-top:50px;
margin: 0;
}
<?php
// Has the text been hidden?
// If so, set display to equal none
if ( 'blank' == get_header_textcolor() ) { ?>
#header h1, #header #desc {
display: none;
}
<?php } else {
// Otherwise, set the color to be the user selected one
?>
#header h1 a, #desc {
color:#<?php header_textcolor() ?>;
}
<?php } ?>
</style>
<?php
}
function admin_header_style() {
// This function styles the admin page
?>
<style type="text/css">
#headimg{
background: url(<?php header_image() ?>) no-repeat;
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width:<?php echo HEADER_IMAGE_WIDTH; ?>px;
padding:0 0 0 18px;
font-family: arial;
}
#headimg h1{
padding-top:50px;
margin: 0;
}
#headimg h1 a, #desc{
color:#<?php header_textcolor() ?>;
text-decoration: none;
border-bottom: none;
}
#desc {
padding-top: 15px;
margin-right: 30px;
}
<?php if ( 'blank' == get_header_textcolor() ) { ?>
#headimg h1, #headimg #desc {
display: none;
}
#headimg h1 a, #headimg #desc {
color:#<?php echo HEADER_TEXTCOLOR ?>;
}
<?php } ?>
</style>
<?php
}
/* This is the key function call, it communicates with the API
and adds the options to the admin menu. You pass the names of your
two styling functions, first the one that styles the theme, then
the one that styles the admin page*/
add_custom_image_header('header_style', 'admin_header_style');
?>
Using It
Once you’ve done the hard work of setting it all up, actually using it to change the header is very, very, simple. You effectively have four options. You can hide the text, change the text colour, revert to the original settings or upload (and crop) a new background image. If you change the color, you’re given a nice color picker to help you out.
The following is a worked example, using WordPress 2.5. Pre 2.5 may look a bit different, but the functionality doesn’t differ.
Step 1
We start out, using the theme page posted above, we have the following header.
Step 2
We go into the admin interface, and get the following screen.
Step 3
We hide the text, and it’s immediately reflected in the admin interface. Note that it won’t be reflected in the theme until it’s been saved.
Step 4
We upload a new image that is larger than the default size we set earlier. WordPress knows this so it allows us to crop the image.
Step 5
The new (incredibly classy) header is shown in the admin area, and in the theme.
Summary
I hope you enjoyed this lengthy guide. Let us know if you end up using it in a theme. I think it’s a must if you plan on openly releasing a theme to the public.
For more information on custom headers, see this post by Boren, one of the WordPress contributors.
» Read the other articles published in Issue 2
Probably got a bit confused in the above discussion.
Is it possible to create a separate header that is only applied to certain pages templates created in word press. Have been experimenting but seem to get a fatal error.
So you would have default header for the homepage, and use another header for selected pages.
Just putting it out their
1
Written by James on June 4th, 2008 at 6:51 pm
As far as I’m aware, you can only have one custom header per blog. What you could do though, is use conditional tags to show different headers based on the type of page being viewed. One of those headings could be a custom one.
Hope that helps.
2
Written by Simon on June 6th, 2008 at 6:26 am
[...] More Details on WordPress’s Custom Headers API→ [...]
3
Written by More Details on WordPress’s Custom Headers API :: WPLover on July 7th, 2008 at 1:03 am