Although there was initially a lot of fanfare over the new “thumbnail” features that were added to WordPress when version 2.9 was released, the documentation for the various functions related to post thumbnails is still severely lacking. In this article, I hope to shed a little light on the subject, as far as I can understand it. There are four new functions related to post thumbnails. Following are some short explanations about what the functions do and how to use them.
has_post_thumbnail()
The point of this function is simply to find out whether or not a post has an associated thumbnail. The function simply returns boolean true or false indicating whether or not the post has a thumbnail.
You can call the function without any parameters – has_post_thumbnail() – and it will pull the ID of the current post. If you want to check on a specific post, you can feed an ID into the function – has_post_thumbnail(123) – where “123” is the wordpress numerical ID of the specific post you’re checking.
get_post_thumbnail_id()
This function is extremely similar to has_post_thumbnail(), except that this function actually returns the numerical ID of the attachment that’s being used as the post thumbnail if one exists. As with has_post_thumbnail(), you can call the get_post_thumbnail_id() without any parameters, or you can feed it a post ID to get a specific post’s thumbnail.
get_the_post_thumbnail()
The next function, which is the real crux of the whole post thumbnail concept, is get_the_post_thumbnail(). This function is used to actually retrieve the HTML code you need to display and/or manipulate the post thumbnail.
The get_the_post_thumbnail() function accepts three optional parameters:
- post ID – the numerical ID of the post for which you want to retrieve the thumbnail
- size – contrary to what you may see in various documentation, the default for this parameter is not to return the thumbnail-sized (usually 150×150, I think) version of the image; it is actually to retrieve the size of the image defined in the theme’s functions.php file with the
set_post_thumbnail_size()function. If you don’t call theset_post_thumbnail_size()function anywhere in your functions.php file, I believe theget_the_post_thumbnail()function returns the full-sized (original) version of your image.You have five choices for the size of the returned image. The first of which is the default ‘post-thumbnail’ (explained to the best of my understanding above). The others are as follows.- ‘thumbnail’ – the default thumbnail size of the image (I believe the WordPress default is 150×150, cropped to a square)
- ‘medium’ – the standard WordPress medium-sized image (maximum of 300×300, resized proportionally without cropping)
- ‘large’ – the standard WordPress large-sized image (maximum of 1024×1024, resized proportionally without cropping)
- custom – you can provide an array with two elements – width and height, respectively – to set a custom size for the image. I’m not sure whether the returned image is cropped or sized proportionally
- attributes – there is still very little documentation on what this parameter does, and it’s difficult to trace through the various function calls to which this parameter is fed. However, the best I’ve been able to ascertain is that there are four different attributes you can send through this parameter.Based on the documentation I’ve found, they seem to be extra query parameters for finding the image, but I think these are actually used to add extra information to the
<img>tag that’s generated by the function.Those attributes are:- src – can be used to override the “src” attribute in the
<img>tag - class – the CSS class that should be applied to the image
- alt – the alternate text that should be used for the image
- title – the HTML title to use for the image
The attributes are actually used by the
wp_get_attachment_image()function, which is called from within theget_the_post_thumbnail()function. - src – can be used to override the “src” attribute in the
Again, the get_the_post_thumbnail() function returns an HTML <img> tag with all of the appropriate attributes set. Unfortunately, there is no simple way (as of yet, at least) to retrieve the appropriate attributes in a PHP array or anything, so, if you want to manipulate them after you retrieve them, you’re going to have to parse the <img> tag yourself and change them around.
the_post_thumbnail()
Finally, there is the_post_thumbnail(), which simply prints out the <img> tag returned by the get_the_post_thumbnail() function. It accepts all the same parameters as get_the_post_thumbnail() and returns the same result. The only difference is, the the_post_thumbnail() actually outputs the <img> tag instead of simply returning it to be stored in a variable.
Hopefully this information will help you figure out how to use the new post thumbnail features available in WordPress. More information is available in the following locations:
- Mark on WordPress: Post Thumbnail Images – a good article on adding post thumbnail support to your theme
- Alex Mansfield: WordPress Image Sizes – a generic article about the default image sizes offered in WordPress
- WordPress Source Code: Post Thumbnail Template – the source code for the four functions described above (from the version 2.9 source)
- WordPress Source Code: Media Functions – the source code from wp-includes/media.php, which includes various attachment functions used by the post thumbnail functions (from the version 2.9 source)
- WordPress Codex:
get_the_post_thumbnail()– the currently limited documentation on theget_the_post_thumbnail()function - WPEngineer: The Ultimitative Guide for the_post_thumbnail in WordPress 2.9 – a really good article explaining how to use the the_post_thumbnail() function