WPX: The Post Thumbnail, Enhanced

Often you want to highlight a title of an article putting aside an image, more appropriately a thumbnail. WordPress offers a function for that scope, the_post_thumbnail. In order to make use of it, you need to activate the relative support, and to set a Featured Image in the proper panel while editing the post. To make things easier, you can use the WPX The Post Thumbnail plugin that activates all the necessary lines of code, straight from the Plugins page and gives you a bit more power and flexibility under your fingers. The plugin adds a new function to the pool, called wpx_the_post_thumbnail that accepts a series of parameters to tune the output and fit your purposes.

With this article I open a new typology of plugins on this website. Defined as WordPress Extend, acronym WPX, they are meant to extend some of the basic functionality of WordPress. Useful to design or improve themes. This time I introduce you WPX The Post Thumbnail.

The best usage for wpx_the_post_thumbnail is in the Front page, Archive and Category pages, or lists of articles where you aim to attract the attention of the readers with small pictures beside the title.

It uses the Featured Image, or if this is missing or has not been properly set, it extracts the first pictures in the content. This way you can make things easier for your customers, too. It then uses Timthumb v2 to crop the image to the dimensions you specify.

You can use it as a plugin, or if you prefer you can copy and paste the function wpx-the-post-thumbnail into your functions.php file. For a better use, please consult the examples at the bottom of this page.

The plugin does not write on the database and it has no option page due its simplicity. Once activated from the Plugins panel, you need to add the function into your template. Usually into the loop, just before the_title and the_content.

<?php while ( have_posts() ) : the_post(); ?>
<div class="the-post">
	<?php wpx_the_post_thumbnail(); ?>
	<?php the_title(); ?>
	<?php the_content(); ?>
</div>
<?php endwhile; ?>

The code above is a pure sequence of elements that composed an example of loop. Obviously a more solid theme performs a better data management in its loop, adding permalink, metadata, comments, and so on.

Installation

Download the plugin. Then extract and copy the folder wpx-the-post-thumbnail into the directory plugins of your installation of WordPress. At this point, from the Dashboard, panel Plugins, you should be able to activate it.

Be sure that the permission for the cache folder for TimThumb is set on 777, or the script will not be able to write into it.

Usage

The function accepts an array of elements as argument. Below we’re passing a full set of values.

<?php // example of usage with all the arguments (in this case, the defaults)
$args = array(
	'width'			=> 150,
	'height'		=> 150,
	'zoom'			=> 1,
	'quality'		=> 75,
	'placeholder'	=> false,
	'alt'			=> 'title',
	'title'			=> 'title',
	'a-class'		=> 'post-thumbnail-permalink',
	'img-class'		=> 'post-thumbnail',
	'thumb-size'	=> 'thumbnail'
);
wpx_the_post_thumbnail( $args ); ?>

It’s not mandatory to pass all the arguments. Say you want the thumbnail to be 200 pixels wide and 120 pixels tall, and to target the link with a custom class. You can pass just those values.

<?php args = array(
	'width'		=> 200,
	'height'	=> 120,
	'a-class'	=> 'my-custom-class'
);
wpx_the_post_thumbnail( $args ); ?>

Let’s see now few notes about the parameters that you can use to tune the final output.

width

It sets the width of the final picture, in pixels. If Zoom is set to 1, the image will be cropped, if set to 0, the final picture may be deformed to fit the desidered width and height.

height

It sets the height of the final pictures, in pixels. If Zoom is set to 1, the image will be cropped, if set to 0, the final picture may be deformed to fit the desidered width and height.

zoom

If set to 1, the final picture will be cropped to save the correct proportion of the image. If set to 0 the image may be deformed to fit the desidered width and height. The default is 1.

quality

It sets the level of compression for the final image. Maximum is 100, default is 75.

placeholder

In case of a broken link to the image, you can set the path to a placeholder so that to have anyway a thumbnail. It’s possible to customize the image used as placeholder (see later).

alt | Alternative Text

If the picture for the thumbnail can’t be visualized for any reason, this is the text that is supposed to describe what is missing. By default is equal to the title of the post. You may want to populate this field with the Excerpt of the Post, so it accepts two values, 'title' or 'excerpt', like below.

$args = array(
	'alt'	=> 'title',
);

…or…

$args = array(
	'alt'	=> 'excerpt',
);

Please note that in case you chose to populate the field with the Excerpt, this has to be clean from any HTML tags (as it is by default). Otherwise those tags may break the HTML flow with unpleasant and unexpected results.

title

Simple as that, at the moment 'title' is the only value accepted by… ehr… 'title'. In practice, when the pointer of the mouse (or the focus) is on the thumbnail, a tooltip should appear displaying the title of the post.

a-class | Anchor’s Class

The thumbnail is embraced in a link, so that it’s possible to click on it, and go to the relative article. By default the anchor has the class 'post-thumbnail-permalink'. You can specify more than one class: just leave a blank space between them.

$args = array(
	'a-class'	=> 'first-class second-class third-class',
);
wpx_the_post_thumbnail();

This makes possible to target and style the thumbnail via CSS at wish.

img-class | Image’s Class

You can specify a class for the image tag, too, to properly target and style it by CSS. By default the img tag has the class 'post-thumbnail'.

thumb-size

In the present release, this values is not used, but I’m planning to implement it. So if you think it can be useful, please let me know and I’ll speed up. As for the the_post_thumbnail(), this parameter is thought to let you pass the size you want to use for the thumbnail. Three different sizes can be set up under Settings > Media: Thumbnail, Medium, Large. You can also add new sizes with the function add_image_size (for more details about this topic, check out the relative page on Codex).

Output

The example below should give you an idea about the output, and what you may do to style it.

<a href="http://mywebsite.com/myarticle" class="post-thumbnail-permalink" alt="Hello world!" title="Hello world!"><img class="post-thumbnail" src="http://mywebsite.com/wp-content/plugins/wpx-the-post-thumbnail/timthumb.php?src=http://mywebsite.com/wp-content/uploads/picture.jpg&amp;w=150&amp;h=150&amp;zc=1&amp;q=75" alt="Hello world!" title="Hello world!" width="150" height="150" /></a>

WPX The Post Thumbnail

If you prefer to copy and paste the function into your functions.php file, you may want to grab the bunch of coding here below. You may need to fix the link to Timthumb and to the image to use as placeholder.

/*------------------------------------------*/
/*	WPX The Post Thumbnail / Plugin	*/
/*------------------------------------------*/

If ( ! function_exists( 'wpx_the_post_thumbnail' ) ) {
	
	// Add support for the post thumbnails
	add_theme_support( 'post-thumbnails' );

	function wpx_the_post_thumbnail($args = array()) {
	
		// setting up the variables
		global $post;
		$img_URL = '';
		$permalink = get_permalink();
		$post_excerpt = get_the_excerpt();
		$post_title = get_the_title();
		
		// defining the defaults
		$defaults = array(
			'width'			=> 150,
			'height'		=> 150,
			'zoom'			=> 1,
			'quality'		=> 75,
			'placeholder'	=> false,
			'alt'			=> 'title',
			'title'			=> 'title',
			'a-class'		=> 'post-thumbnail-permalink',
			'img-class'		=> 'post-thumbnail',
			'thumb-size'	=>	'thumbnail'
		);
		
		// parsing the settings provided against the defaults
		$parsed = array();
		$parsed = wp_parse_args( $args, $defaults );
		
		// saving our working variables
		$width			= $parsed[ 'width' ];
		$height			= $parsed[ 'height' ];
		$zoom			= $parsed[ 'zoom' ];
		$quality		= $parsed[ 'quality' ];
		$placeholder	= $parsed[ 'placeholder' ];
		$alt			= $parsed[ 'alt' ];
		$title			= $parsed[ 'title' ];
		$a_class		= $parsed[ 'a-class' ];
		$img_class		= $parsed[ 'img-class' ];
		$thumb_size		= $parsed[ 'thumb-size' ];
		
		// populating $alt and $title
		if ( $alt == 'alt' ) {
			$alt = get_the_excerpt();
		} else {
			$alt = get_the_title();
		}
		$title = get_the_title();
		
		//	and now let's roll!
		if ( has_post_thumbnail() ) {
		
			//	if the user has already set a thumbnail, let's use it
			$img_id = get_post_thumbnail_id();
			
		} else {
		
			//	else if there is not post_thumbnail, we try to get an image among the content
			global $wpdb;
			$img_id = $wpdb->get_var( "SELECT ID FROM $wpdb->posts WHERE post_parent = $post->ID AND post_mime_type LIKE 'image%' ORDER BY post_date DESC LIMIT 0, 1" );
		}
		
		//	if we collected an ID, we can use it to set the $img_URL for the pic
		if ( $img_id ) $img_URL = wp_get_attachment_url( $img_id );
		
		//	if $img_URL is still empty, we collect the defaul replacement out from the theme
		//	remember to put an image in the folder (and eventually to provide the correct folder below)
		if ( ! $img_URL && $placeholder == true ) $img_URL = ( plugins_url() . '/wpx-the-post-thumbnail/images/thumb-placeholder.jpg' );
		
		//	in the end if finally we have an image, we can then display the code
		//	that also means, if $placeholder is set as false,
		//	and we don't get any image, no code is printed on page
		if ( $img_URL ) {
			$output = '<a href="' . $permalink . '" class="' . $a_class . '"';
			$output .= ' alt="' . $alt . '" title="' . $title . '">';
			$output .= '<img class="' . $img_class . '" src="' . plugins_url() . '/wpx-the-post-thumbnail/timthumb.php?src=';
			$output .= "$img_URL&amp;w=$width&amp;h=$height&amp;zc=$zoom&amp;q=$quality";
			$output .= '" alt="' . $alt . '" title="' . $title . '" width="' . $width . '" height="' . $height . '" /></a>';
			print $output;
		}
	}
} // END

Examples of usage

This section will be in progress for a while, collecting data.

First thing, it’s a safe practice to verify if a function is available before to actually call it.

if (function_exist ( 'wpx_the_post_thumbnail' ) ) {
	wpx_the_post_thumbnail();
}

This way, if the plugin isn’t active, you do not incur in errors, or broken HTML.

Align Left!

Often you want to have the thumbnails on the left of the title. Most themes for WordPress provide already a class to set an element floating on a side, in our case 'alignleft'.

$args = array(
	'a-class'	=> 'alignleft post-thumbnail-permalink',
);
wpx_the_post_thumbnail( $args );