Dan Birlew

Las Vegas Web Developer, Designer, Programmer, and Author

Editable WordPress Post Thumbnails in a Layout

Posted July 21st, 2014 at 8:46am by Dan Birlew in Blog, WordPress. Comments Off on Editable WordPress Post Thumbnails in a Layout

Using WordPress post thumbnails in themes is easy. Ensuring that those who use your theme can edit their post thumbnails without completely breaking the layout is tricky, however.

WordPress is the most popular blogging and CMS script in the world, partly because it contains a robust media uploader and editor. Each time you upload an image, WordPress automatically creates as many thumbnail and post sizes as you care to specify, either via the Media page in the Settings or by adding code to your theme’s functions.php file. The system even features a way to edit images online and save the results. Edits can be saved to all image sizes, just the thumbnail, or all sizes except the thumbnail.

Custom image sizes can be used to produce gorgeous layouts. There’s also a built in system for setting a Featured Image for a post. That way it becomes easy to create a layout full of post excerpts with images. For examples check out the front pages of these sites I’ve built: http://lollieshopping.com, http://lasvegasmanblog.com and http://blog.totalrewards.com/las-vegas. The layout shows just enough to get you interested enough to click through and view the full post. I prefer this approach because it encourages click-throughs to posts, and yes, it makes tracking analysts quite happy.

The problem I’ve been having is that my clients want to be able to upload an image, crop it within WordPress, and then use the edited image as the Featured Image for the post. And I acknowledge that this actually works, but only when your WordPress site has been set up a very specific way.

What Are We Even Talking About?

First, if you’re lost, let’s start with the basics. When you upload an image, WordPress creates the following sizes:

  • thumbnail

The ‘full’ size is the original image. The other sizes are determined by the settings the user inputs at Settings > Media in the menu. The ‘thumbnail’ size is the one that can be modified in the media editor and saved in isolation, without changing the original image. Once edits are made to a thumbnail, WordPress uses the edited version instead of the original.

This is where WordPress can go wrong, because if you want to use the thumbnail size in your layout and the user changes that size in the settings, then what happens to your layout? Regardless of your html and css skills the layout likely falls apart, or the resized image must be stretched in width or height to fill the space.

To prevent the user from changing the thumbnail size and potentially breaking your layout, WordPress instituted the set_post_thumbnail_size function. By adding this to the functions.php file in your theme, you force WordPress to add an additional thumbnail size with a hard or soft crop to your size specifications.

However, this function does not set the size for the ‘thumbnail’ that is editable by the user. This function merely uses the add_image_size function to create and use another image size called ‘post-thumbnail’. This is the size that is used by default by the function the_post_thumbnail, which is the function that allows you to use the Featured Image of a post in your layouts.

But How Do I Use Featured Images?

WordPress has a function called Featured Images that allows you to attach a meaningful or representative image to a post. The Featured Image can then be utilized in your theme layouts. First, you must activate Featured Images in your theme by adding the following line to your functions.php file:

     'post-thumbnails' );

Now if you add or edit a post you’ll see a new box in the right column of the edit post page, titled “Featured Image”. Clicking the link in this area opens the media uploader so that you may upload, select, and set a featured image for the post.

To use the Featured Image in your layout insert the following into single.php, index.php, or wherever your layout appears:

<?php the_post_thumbnail(); ?>

Without any declarations, this function inserts the Featured Image that is attached to the post. The first declaration you can set for this function is the image size to use. Unless a size is declared, the_post_thumbnail uses the ‘post-thumbnail’ size, which as mentioned before is set by adding the following:

      $width, $height, $crop );

Add this line to your functions.php file in your theme and replace the variables with integers (true or false also works for $crop). WordPress automatically creates the thumbnail size you need, and you can then use it in a layout without worrying that the wrong size will be displayed by the_post_thumbnail. This allows the end user to change the settings on the Media page without affecting the layout: the thumbnails remain isolated, unchanged, and still display at the size that you, the designer/developer, intended.

However, because the ‘post-thumbnail’ is not the same as the ‘thumbnail’, this size cannot be edited in isolation within WordPress: it can only be modified by the WordPress media editor by saving your changes to all image size or all except thumbs. This is hardly desirable, as usually most people go to great lengths to create a nice large image to use at the top of posts and then just want a small crop to use in layouts. But they also want to be able to control how that image is cropped; no one wants to cut off someone’s head or cut a logo in half.

Aside, note that this means that the information on WordPress.org’s Post Thumbnails explanation page (for users) regarding Thumbnail Sizes is actually wrong and misleading (and also caused me to spin in circles):


The information is outdated in numerous ways, but the worst offense is in declaring that the ‘thumbnail’ size is still the default for the function, the_post_thumbnail. This is how the_post_thumbnail PREVIOUSLY worked, but the functionality was changed several versions of WordPress ago.

Using the Editable Thumbnail in Layouts

So let’s get to it. To make the thumbnail in your layout editable by WordPress, you must insert the following into the relative theme file:

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

Notice that I specified the optional image size for WordPress to display. As explained, we don’t want WordPress to use the un-editable ‘post-thumbnail’ size because it is simply a static image. You can set whether WordPress will hard crop or soft crop this image during the automatic creation process, but that’s it. The user has no ability to fine tune.

It gets worse. If you add the_post_thumbnail() to your theme without settings and without declaring set_post_thumbnail_size() in your functions.php, then WordPress doesn’t know what size it’s looking for. Literally. Because all set_post_thumbnail_size does is run the add_image_size function for the settings you enter. And worse, the_post_thumbnail doesn’t check to see if set_post_thumbnail_size has been set.

Preventing the User from Breaking Thumbnails

Therefore, the only way to make the post thumbnail editable within WordPress is to specify use of the ‘thumbnail’ size in the_post_thumbnail function. This means that you either have to set the thumbnail sizes for them when setting up their site, or taking control out of their hands permanently:

    'thumbnail_size_w', 320 );
    'thumbnail_size_h', 160 );
    'thumbnail_crop', 1 );

Add these lines to your functions.php file, and then go to Settings > Media and try to change the thumbnail size. You can’t. And neither can your client. You’ve effectively taken control of the situation with your theme.

The Brass Tacks

Here’s the issue in a nutshell:

  • If you declare set_post_thumbnail_size in your functions.php and insert the_post_thumbnail() without parameters into your layout, then you can guarantee that the image size used in your layout cannot be broken by the end user. However, the image cannot be edited.
  • If you instead insert the_post_thumbnail( ‘thumbnail’ ) into your layout, then the thumbnail can be edited. However, the thumbnail settings on the Media page must be set to the right dimensions, at all times. Also the user might break the layout in various ways: by changing the thumbnail size in the Media settings, by cropping the ‘thumbnail’ to a weird size that no longer fits the layout, and probably even more ways I can’t think of. Using the update_option function prevents the user from changing the thumbnail size settings, but they can still break the thumbnail by cropping it to a different size in the media editor.

To REALLY fix this, the programming of these the_post_thumbnail needs to be modified in future WordPress releases along the following lines:

  1. If set_post_thumbnail_size is set, let’s boolean a flag
  2. the_post_thumbnail needs to check the boolean above to determine if set_post_thumbnail_size has been set. If so, then the ‘post-thumbnail’ size needs to be used as the default thumbnail size returned by the function. If not, then the ‘thumbnail’ size needs to be used
  3. OR, (bonus), get rid of the ‘post-thumbnail’ size altogether and go back to using ‘thumbnail’. And set_post_thumbnail_size needs to be re-scripted to override the user’s settings on the Media page

I don’t know what solution would work best because I am not on the WordPress dev team. I do not know the intricacies and perhaps caveats of the media uploader script they are currently using, and therefore I can only suggest possible changes and leave that to them. However, you as a WordPress developer now have the ability to use the editable ‘thumbnail’ size in your layouts and reduce the ability of unknowledgeable users to break them.

Tags: , ,

Comments are closed.