Practical Uses for the Post-Thumbnail Function in WordPress 2.9

We are all used to seeing an image below blog posts titles, be it on blog homepages or on individual posts. However, until recently, adding these images was not as straightforward. Before the ability to register post thumbnails in themes was introduced in WordPress 2.9, WordPress theme developers were forced to use the post metadata in order to display an image associated with a post. In this tutorial, I’ll show you how to add this functionality to your themes and we will play around with some of the function options.

Post-Thumbnail Function in WordPress 2.9

Practical Uses of WordPress Post-Thumbnail Function

Enabling the Post Thumbnail Functionality in your Themes

Enabling this functionality in your themes is actually so simple. All you need to do is add one line to your functions.php file (or two lines if you’d like a descriptive comment):

// Enable post thumbnails
add_theme_support('post-thumbnails');

Inserting post thumbnails

When you go to your WordPress admin panel and start writing a new post, you should see a new box on the right side of the page.

Set Thumbnail

Please note that the Post Thumbnail block might not appear immediately below the Publish block, you might have to scroll down a little to see it. Clicking the Set Thumbnail link opens the Add an Image dialog.

Use as Thumbnail

Click on the Use as Thumbnail link and it will be added to your post:

Show Thumbnail

Displaying the post thumbnails

After adding some dummy text to our post, we are ready to publish it. But before we preview the thumbnail, we’ll have to add a line of code to our WordPress loop. Open your index.php and add the following:

<?php the_post_thumbnail(); ?>

That will output an image tag with these classes: attachment-post-thumbnail and wp-post-image so that you can target your post thumbnails with CSS and style them to your liking. For this tutorial, I am using the theme I use for my website so there’s already a bit of styling applied, a border and some padding, nothing fancy.

Half Thumbnail Size

Above is our post with the thumbnail displayed on the homepage. There is a problem, however, it is quite easy to resolve. My site uses a specific size for thumbnail images; it is 588 by 250 pixels. You can set this for your own WordPress blog by going to Settings > Media in your WordPress admin panel.

Media Settings

Another method you can use to make sure your thumbnails are the right size is to add their dimension to your functions.php file. To do this, we’ll add another line to our post thumbnail related code:

// Enable post thumbnails
add_theme_support('post-thumbnails');
set_post_thumbnail_size(588, 250, true);

Now we need to tell WordPress that it should display the image in this exact size. We’ll slightly modify the bit of code that was added to the WordPress loop in the index.php file:

<?php the_post_thumbnail('thumbnail'); ?>

WordPress now knows which version we want it to display in the loop and here is the improved result:

Full Thumbnail Size

We will add the bit of PHP used for displaying thumbnails to our single.php as well so that we can see it when we open the posts.

Top Thumbnail

That looks nice satisfactory, depending on your blog design, that could be all that you need to know about the post-thumbnail function. But we won’t stop here.

Adding more post thumbnail sizes

If you want your blog homepage to show post thumbnails in one size, and the posts to be displayed in a different thumbnail size, this is how you achieve it.

I will be using an image prepared in Photoshop; it’s a post thumbnail for one of my portfolio items. This bit about changing the thumbnail isn’t important for this tutorial so you can skip ahead to the part where we add more code to the PHP files.

The first thing to do is to remove the thumbnail that we’ve already assigned and add the new image as the post thumbnail. Removing the thumbnail is easy; just click the Remove Thumbnail link on the Edit post page in the WordPress admin:

Remove Thumbnail

You already know how to add a thumbnail so we won’t go into that again. Here is the homepage with the new thumbnail added:

Large Thumbnail

The idea here is to use a smaller image for the homepage and the original-sized image for the posts. So we’ll need to create a new image size in our functions.php file.

add_image_size('loopThumb', 588, 125, true);

The arguments in the code above are:

  • loopThumb – a handle assigned to our custom-sized images;
  • 588 – image width in pixels;
  • 125 – image height in pixels;
  • true – a setting that tells WordPress whether to hard crop the image to reach the desired size.

We will need to alter the code in our index.php so that WordPress shows the new thumbnail size on the homepage:

<?php the_post_thumbnail('loopThumb'); ?>

Thin Thumbnail

I prefer this version because the slimmer images appear as teasers, as windows into the post thus inviting the visitor to open the post and continue reading.

Please note that changing the the_post_thumbnail call will not only alter the image size but also the CSS classes of the image. We now have these two classes for our image: attachment-loopThumb and wp-post-image. It might be safer to target the wp-post-image class in your CSS just to be on the safe side or add your own class when calling the thumbnails:

<?php the_post_thumbnail('loopThumb', array('class'=>'loopyThumbs')); ?>

That will output an img tag with the following classes: loopyThumbs and wp-post-image; quite useful.
If you want to display square images on the homepage, all you would need to do is to change the width and height in the add_image_size call:

add_image_size('squareThumb', 125, 125, true);

You’d probably want to float the attachment-post-thumbnail class to the left and add a right margin in your CSS:

.attachment-post-thumbnail {
	float: left;
	margin-right: 10px;
}

Now we change the code in index.php again so that the new square thumbnails will be displayed:

<?php the_post_thumbnail('squareThumb'); ?>

And that’s all we need to display the square thumbnails as seen in the screenshot below.

Small Thumbnail

Well that’s not an exact square isn’t it? This is the problem you’ll run into if you add a new image size after you’ve already uploaded some images to your site. WordPress didn’t create the image size that you need so what you’re seeing is an image resized by the browser. Luckily there is a solution for this, a plugin called Regenerate Thumbnails. After you’ve added a new thumbnail size or changed any of the image sizes in the Media settings section of the admin panel, it will recreate the images into the necessary size.

After you install the plugin, you can regenerate all the images by going to Tools > Regen. Thumbnails and clicking the Regenerate all Thumbnails button. And now we’ll have properly squared images.

Square Thumbnail

And that’s another problem solved.

Bulletproofing your Themes

Before WordPress 2.9 introduced post thumbnails, we had to rely on the post metadata also known as custom fields. Let’s say you’re building a WordPress theme that you plan on uploading to an online marketplace. You can only hope that people buying your theme will have blogs running the latest version of WordPress which has the post thumbnail support. However, there is a good chance that whoever purchases your theme has a blog running on an older version because they did not upgrade to the latest version of WordPress. There are a couple of simple if checks that will help us prepare the theme for all users.

First we want to check if the version of WordPress has the support for post thumbnails so here is the code we will add to the functions.php file:

if (function_exists('add_theme_support')) {
	add_theme_support('post-thumbnails');
	set_post_thumbnail_size(588, 250, true); // Normal post thumbnails
	add_image_size('loopThumb', 588, 125, true);
}

We have wrapped our original code in an if check that verifies the new function exists and will only be called if it does exist.

Things get a little more complicated when we address the code that displays the post thumbnails. You’ll remember that was quite simple:

<?php the_post_thumbnail('loopThumb'); ?>

Now, we will want to check if there is a post thumbnail assigned to the post. If not, we will display an image that is set via the custom fields. And, as the final resort, if it can’t find anything, WordPress will display a default post image.

<?php
if (has_post_thumbnail()) {
		the_post_thumbnail('loopThumb');
	}
	elseif (get_post_meta($post->ID, "Thumbnail", true) != '') { ?>
		<img src="<?php echo get_post_meta($post->ID, "Thumbnail", true); ?>" alt="<?php the_title(); ?>" class="attachment-loopThumb wp-post-image" />
	<?php }
	else {
		echo '<img src="images/defaultThumbnail.png" class="attachment-loopThumb wp-post-image" alt="Default Post Image" />';
	}
?>

In the code above, the first if check verifies whether there is a post thumbnail. If there is one, it outputs the img tag with the post thumbnail. In case it doesn’t find a post thumbnail, we have a new check. This one looks for a custom field named Thumbnail which would be the URL to the post image. If one is found, it echoes out the img tag with the thumbnail image as its source.

Finally, if there is neither the post thumbnail nor the custom field with the thumbnail URL, we will echo out an img tag with a default post image.

Advantages of Using Post-Thumbnail over Get-Post-Meta

In closing, I want to cover a couple of benefits that you’ll gain from using the new post-thumbnail functionality. One of them is reducing MySQL queries. The post-thumbnail data is stored in the wp_post MySQL table which is normally called when you open a post. Earlier, when we had to rely on custom fields to insert post thumbnails, the browser would have to make a request to the wp_postmeta table, increasing the number of database queries.

I should also mention that there is an option to limit the post-thumbnail functionality to certain types of content. For example:

<?php add_theme_support('post-thumbnails', array('page')); ?>

The snippet of code shown above adds the post-thumbnail functionality only to pages and not to posts. WP Engineer recently shared their first impressions of Custom Post Type coming in WordPress 3.0 and it looks like we’ll (should the need arise) be able to add post thumbnails only to certain post types.

Imagine a music blog that would have posts with album reviews and posts regarding the site itself with which you do not wish to associate a thumbnail, it would be very easy to limit the thumbnail support only to reviews.

If you are running a blog on an older version of WordPress, I hope that this article has encouraged you towards upgrading. And if you’re worrying about creating new thumbnail image sizes, let me remind you of the Regenerate Thumbnails plugin.

Conclusion

I hope that you’ve enjoyed this article and that it has provided enough information on the post-thumbnail function. I hope that you’ve learned some new techniques and if you have any questions or suggestions, don’t hesitate to post them in the comment box below.