Quick Tip: Using BFI Thumb for Custom-Size Featured Images

As WordPress theme developers, we might create a theme - or themes - that require images to be of a certain specific size (dimensions). At the same time, we can’t place the responsibility of creating such dimension-specific images on the end users of our themes.

So what is the solution? The best way to deal with this problem is to incorporate within our theme(s) the functionality to generate custom-sized images on the fly.

In this tutorial, I am going to show you how to use the BFI Thumb PHP library to achieve that.

Featured Images

What Are Featured Images

According to the WordPress Codex:

A Featured Image is an image that is chosen as the representative image for Posts, Pages or Custom Post Types. The display of this image is up to the theme. This is especially useful for "magazine-style" themes where each post has an image.

Featured Images were called Thumbnails before the name was changed. So you will find these two terms being used interchangeably.

Enabling Support for Featured Images

Themes have to declare their support for post thumbnails before the interface for assigning these images will appear on the Add Post/Edit Post screens.

To enable post thumbnail support in your theme, add the following line to your functions.php file:

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

Displaying Post Thumbnails in Your Theme

To display post thumbnails in your theme, paste the following code at an appropriate place in your specific template file:

<?php 
if ( has_post_thumbnail() ) { // check if the post has a Post Thumbnail assigned to it.
  the_post_thumbnail();
} 
?>

The above code checks to see if the post has a thumbnail before calling the function to display it.

The add_image_size() function

The add_image_size() function enables you to register new image sizes for post thumbnails.

By default, WordPress creates the following image sizes when a user adds an image to the Media Library:

thumbnail – (150px x 150px max)
medium – (300px x 300px)
large – (640px x 640px)
full – original size uploaded

Registering New Image Size

To register new image sizes, we use the add_image_size() function like this:

<?php 
add_image_size( $name, $width, $height, $crop ); 
?>

Parameters:

$name - (string) (required) The new image size name. Default: None
$width - (int) (optional) The post thumbnail width in pixels. Default: 0
$height - (int) (optional) The post thumbnail height in pixels. Default: 0
$crop - (boolean/array) (optional)

Example Usage

<?php
if ( function_exists( 'add_image_size' ) ) { 
    add_image_size( 'category-thumb', 300 ); // 300 pixels wide (and unlimited height)
	add_image_size( 'homepage-thumb', 220, 180, true ); // (cropped)
}
?>

To display the newly-registered image sizes in your theme, simply pass the name of your custom post thumb image size to the the_post_thumbnail() function, like this:

<?php 
if ( has_post_thumbnail() ) { 
  the_post_thumbnail(‘category-thumb’);
} 
?>

Introducing BFI Thumb

BFI Thumb is a PHP class or library that acts as an on-the-fly image resizer / cropper / grayscaler / colorizer / opacitor for WordPress developed by Benjamin Intal.

Installation and Integration

1. Download BFI thumb from GitHub and save it in your theme’s root directory.

2. Include in your theme by adding the following line to your functions.php file:

<?php
require_once('BFI_Thumb.php');
?>

3. Use the following function wherever you want to display your custom-sized image:

<?php 
// Resize by width and height
$params = array( 'width' => 400, 'height' => 300 );
bfi_thumb( "URL-to-image.jpg", $params );
?>

If you look at the above function ( bfi_thumb() ), you will notice that it takes the URL of the image to be resized as a first parameter, followed by the other parameters (image dimensions). So you must be asking yourself, how do we determine the URL of our post thumbnail?

To determine the URL of a post thumbnail, we use a function called wp_get_attachment_image_src() which takes the attachment ID, size and an optional icon as parameters.

<?php wp_get_attachment_image_src( $attachment_id, $size, $icon ); ?>

So we pass get_post_thumbnail_id() function as the first parameter. It takes the Post ID as a parameter and returns the ID of the featured image attached to the post.

The second parameter is size which can be either a string keyword (thumbnail, medium, large or full), any custom image sizes you added using the add_image_size() function or a two-item array representing width and height in pixels. But to ensure that our custom-sized image has the highest quality, we will use the original size – full.

By now our code should look something like this:

<?php 
  $size = 'full';
  $params = array( 'width' => 400, 'height' => 300 );
  $imgsrc = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID, '' ), $thumb_size ); 
  bfi_thumb( $imgsrc[0], $params );
?>

wp_get_attachment_image_src() returns an ordered array with values corresponding to the (0) url, (1) width, (2) height, and (3) scale of an image attachment (or an icon representing any attachment).

But we are only interested in the first returned parameter – the URL. We pass it to the bfi_thumb() function, along with our other parameters (width and height) to get our custom-sized image.

Wrapping It Up in a Function

Because we are likely to use this code over and over in our theme – or themes – let’s wrap it up in a function.

<?php 
function tuts_custom_img( $thumb_size, $image_width, $image_height ) {

  global $post;

  $params = array( 'width' => $image_width, 'height' => $image_height );
  
  $imgsrc = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID, '' ), $thumb_size );
  $custom_img_src = bfi_thumb( $imgsrc[0], $params );
  
  return $custom_img_src;
  
}

?>

Save this file to your functions.php file.

Usage

For images:

<img src="<?php echo tuts_custom_img('full', 300, 400);?>" />

Or for background images:

<div style="background: transparent <?php echo tuts_custom_img('full', 300, 400); ?> no-repeat top center;">
 ...
</div>

Advantages of Custom-Sized Images over Thumbnails

Custom-sized images created on-the-fly using a library like BFI Thumb have the following advantages over custom thumbnails created/added using the add_image_size() function:

the_post_thumbail() functions echoes out an image tag. Sometimes what you want is the url of the image. An example would be where you want to use the image as a background.
Custom image sizes registered using add_image_size() will not apply to older images that were uploaded before the image size was registered
BFI Thumb has the ability to resize images both up and down
BFI Thumb also has additional functions such as: grayscale, color (colorize), opacity, negate

Conclusion

In this quick tip, we looked at featured images - what they are and how we can use them in our themes. We also looked at the add_image_size() function to see how we can use it to add custom image sizes when an image is uploaded into the Media Library.

We introduced the BFI THumb PHP library and illustrated how we can use it to create a custom-sized image from a post thumbnail or featured image.

We then looked at the limitations of using add_image_size() to create custom image sizes and the advantages that BFI Thumb has over it.

Add this function to your functions.php file and use it whenever you need to create a custom-sized image from a thumbnail.

HIGHLIGHTS OF THE DAY