WordPress Theme Lesson 8: Post Thumbnails

In this lesson we’ll go through post thumbnails, a feature introduced in WordPress 2.9. A post thumbnail is an image chosen by the author as the representative image for a post. Having an image to each post makes the site more interesting to look at. Keep in mind that the post thumbnail is not a part of the post’s body content, so it will not appear unless you choose it to.

In our design we want a wide and quite narrow thumbnail above each post on our front page. We also want the same post thumbnail but smaller and square for our featured posts section (the slider we’ll create at the very top of the front page). In this lesson we’ll first add and define these new image sizes and then tell WordPress where to display them. Along the way we will also add some code to exclude images that appear in posts, as not to make the front page look like a mess.

First, a couple of things to note: The feature is generally referred to as post thumbnails, but when the author is to choose an image when editing a post, it will be referenced as “featured image”. And keep in mind that your web server needs the GD library installed in order to have WordPress make copies of images and resize them. You most probably already have this installed. But if you upload images and WordPress can’t seem to make any copies with different sizes, the GD library might not be installed.

First, in our functions.php we need a line adding theme support for post thumbnails, which enables the featured image box in Edit Post in WordPress admin. Then we add code for defining new image sizes, providing unique names and dimensions. Finally we edit our templates, telling WordPress where and which image size we want to display. At the very end of the lesson I’ve added an optional code which filters the_content(), removing all <img> tags, on the front page only. Having the wide post thumbnail and another image just below it (suppose the author has added an image at the beginning of the post) will not look very good.

Adding Support for and Inserting Post Thumbnails

First, we add the theme support for post thumbnails in our functions.php, and by doing so we enable the featured image selector in Edit Post in WordPress admin. Place this anywhere in the functions-file:

functions.php:

add_theme_support('post-thumbnails');

The Featured Image option in Edit Post

Save, go to WordPress admin and edit a post. Look to your right, below the Post tags which resides below Categories and the Publish box. Clicking on the link will take you to the well-known interface for uploading images or choosing images from the library. But for adding post thumbnail you are not to click the “Insert into Post” button.

The Featured Image link in Add Media

If you see to the right of the “Insert into Post” button, you will see a link “Use as featured image”. Whenever you choose a post thumbnail, this is what you click, not the “Insert into Post” button. The Image dialog box won’t close by itself when you click it (just click the X in the corner), but when you close it you will see a thumbnail of your chosen image inside the Featured image box, with an option to remove it.

Do not start uploading images just yet. As for now WordPress will make three copies of your uploaded images, the default Thumbnail, Medium and Large. We want to add a couple of more sizes, telling WordPress to create more copies with our desired heights and widths.

Adding New Custom Image Sizes

Adding a new custom image size is pretty simple, we call a WordPress function in our functions.php for each new image size, providing an unique name, the width and height as arguments. We will add two sizes, one for the front page and one for the featured posts section. Add these lines anywhere in our functions-file:

functions.php:

add_image_size('frontpage-thumbnail', 523, 105, TRUE);
add_image_size('featuredposts-thumbnail', 140, 100, TRUE);

The first parameter to add_image_size() is a chosen shorthand name of our image size, without spaces and no uppercase letters. Whenever we insert a post thumbnail in a template, we will refer to this name. The next two arguments define the width and height, respectively. The last parameter decides whether or not WordPress is allowed to crop the image to force the images to fit into the given dimensions.

With these two lines in your functions.php you can now upload images, and see that five copies are made, the three default Thumbnail, Medium and Large, and our two new sizes. If you already have a Library filled with images, there won’t exist copies in our two new sizes. For this you can use the Regenerate thumbnails plugin to create new copies of already uploaded images.

Displaying Post Thumbnails in Templates

Now that we’ve added the support, defined custom image sizes, and uploaded a least a couple of images for testing purposes, it’s time to tell WordPress to display them. For this we edit the template index.php, inserting the frontpage-thumbnail in each post. As we haven’t written our featured posts section yet, I will only show how you insert the post thumbnails at the front page.

Insert this line after the <h3> post title and before the <div> with the class postcontent:

index.php:

<?php if (has_post_thumbnail()) : ?><div class="postthumbnail"><?php the_post_thumbnail('frontpage-thumbnail'); ?></div><?php endif; ?>

What this line does is to first check whether or not the post has been assigned a post thumbnail. If it does, we insert a wrapping <div> and call the WordPress function the_post_thumbnail() to insert the image. As parameter to the_post_thumbnail() we provide the name of the size we want, in our case frontpage-thumbnail. And that’s it for displaying the post thumbnail!

Let’s add a small piece of CSS into our style.css to improve the look of the post thumbnail images:

style.css:

.post .postthumbnail { 
	border: 1px solid #697f9a;
	width: 523px;
	margin: 6px 0;
}

Save, refresh your front page and see that all posts that has a post thumbnail assigned to it, get a wide image after the title. The post thumbnail is only visible on your front page, not on single views or the other templates, such as the search results or archives. It’s up to you if you want to add post thumbnails to any of the other templates. Just copy the line we inserted into index.php and paste it in the desired template.

Our frontpage with post thumbnails

If your site already has a bunch of posts and you don’t want to edit each post and set a post thumbnail, there’s a plugin that can help you with that. The Auto post thumbnail plugin will generate a post thumbnail from the first image in your post. Keep in mind that you probably need to run the Regenerate thumbnails plugin in order to make copies of all images in the sizes we’ve defined here.

It’s starting to look good, doesn’t it? But if you’re like me, who like to use images in posts, and most often quite early in the post, it may look a little messy with the wide post thumbnail, and a image right below it. In our design it looks more tidy with text only and without any additional cluttering images. That’s why I’ve added a piece of code to exclude all images from the post content on the front page. It’s fully optional to add this piece of code, but it could prove useful to read it as this is the first WordPress filter I’m explaining in this tutorial. If you recall Lesson 1 this is the other kind of WordPress hooks.

WordPress Codex Function references:

Our First Filter: Exclude All Images in Posts at the Front Page

This optional piece of code hooks onto a WordPress filter, as opposed to actions. The method is similar as to what we’ve done with actions earlier; we write a function that modifies a piece of information returned by WordPress, hooks it onto hooks such as the_content(), the_title() or almost any function which returns or stores a piece of information in WordPress, and WordPress will automatically run our function when the situation appears. See a list of all available filters here.

We are to write a filter on the_content(), the function we’ve used in our templates and index.php to display the post content. Basically what we do is using a regular expression to find <img> tags and cut them out, but do so only on the front page. Otherwise all images are cut away from all templates, even single post views. It’s important to remember that we’ve used the_content() on basically every template, and filtering it will affect them all.

Writing a filter is similar to action hooks, we use add_filter() with the filter hook we want to hook this function onto as the first argument. But with filters we need to place arguments to our PHP functions, which is the piece(s) of information we are to modify. More importantly we must remember to return all values when we’re done. If we forget to return it, the filter we’ve hooked onto will return empty. In our case all calls to the_content() will return nothing, and that’s pretty disastrous!

functions.php:

/* Exclude images in the_content on home and frontpage */
function wpthemetutorial_image_content_filter($content) {
	if (is_home() || is_front_page()) {
		$content = preg_replace("/<img[^>]+\>/i", "", $content);
	}
	return $content;
}
add_filter('the_content', 'wpthemetutorial_image_content_filter', 11);

The the_content() requires us to add one parameter to our PHP function, the entire post content which we store in the PHP value $content. First, and importantly, we check if we are on the front page by checking the WordPress conditional tags is_home() and is_front_page(). If that’s the case we run a PHP regular expression replacing any <img> in the content with an empty string. Then we return the content, regardless of what have been done in this function. By using add_filter() we tell WordPress to run our function whenever WordPress runs the_content().

If you refresh your front page, it should still display post thumbnails, but no other images – not even smiley icons are displayed if you’ve enabled WordPress smileys.

WordPress Codex Function references:

This concludes Lesson 8 of the WordPress Theme Tutorial. Go to the next lesson, Adding Support for Custom Menus.