Using the ‘ChoiceCuts Image Juggler’ Wordpress plug-in

In this article I hope to both introduce you to our wordpress plug-in, the ChoiceCuts Image Juggler, and to illustrate a couple of ways it can be used. The plug-in itself is intended for those familiar with Wordpress theme customisation. Put another way, intermediate to advanced Wordpress users.

UPDATE: The plug-in has been updated and version 0.8 is available from the WP repository now. Though the following article is still useful it is now a little out of date. I will do my best to refresh all documentation as soon as possible. Email me at ian@choicecuts.com in the meantime if you have any questions.

We use Wordpress a lot. We find it to be a good fit for many of the website builds we undertake as a CMS platform. That said, it is not uncommon to find a required functionality missing from the Wordpress core. Mostly this is no problem though, as the large wordpress community has usually built a plug-in already to fill the hole.

The CC-ImageJuggler is our way of giving back to the community that has given us so many solutions to potentially time consuming problems.

As we increasingly used Wordpress as a CMS, we found image handling to be an issue that kept coming back to haunt us. Typically, a customer would want a beautifully designed website, rich with imagery. They would have grand plans of  regularly updating their site but here-in lies the problem.

Unfortunetly this earnest intent is not always matched but their knowledge of basic image management. Inevitably our lovely web designs would start to deteriorate due to images which were essential to the structure and balance of a page were either absent or worse, in completly the wrong dimensions.

To resolve this we began developing the CC-ImageJuggler. The aim was to make image management for the end user as simple as possible. Beyond the most basic visual checking, an end user can upload their image as normal, completly disregard all resizing options and carry on about their website updating without another concern. CC-ImageJuggler takes care of the rest, ensureing that all images are presented in the size and dimensions required to maintain consistency, and page layout coherance.

• How Image Juggler works
• Create a series of thumbnails from the latest blog posts
• Automatically resize all images within your Single post view

How Image Juggler works

Now for some background technical stuff, for those that are into that type of stuff.

The CC-ImageJuggler uses the fantastic Thumbnail.inc.php library by Ian Shelby, which can be found at http://trac.gxdlabs.com/projects/phpthumb/wiki/Legacy. What the CC-ImageJuggler plug-in does is bridge the gap between the thumbnail.inc.php and instant wordpress theme or site integration. The ChoiceCuts Image Juggler provides a library of PHP utility, thumbnail.inc.php integration and image presentation functions to help you rapidly make images a strong point of your site, and not the sore point of your development cycle.

A comprehensive readme.txt file is included, which lists all the functions available. Also, I documented the plug-in code extensively in PHPDocumentor compatible format. So if you are really keen to understand exactly how the plug-in works I suggestion looking through the core plugin file, cc_image_juggler.php.

Create a series of thumbnails from the latest blog posts

Now I will attempt to illustrate how the CC-ImageJuggler can be used to create thumbnails from post images on the fly. For this example we are going to create a thumbnail for each of the last 10 posts on our imaginary blog. All in one go the code is as follows…

query_posts("category_name=Blog&showposts=10");
while(have_posts()) {
	the_post();
	ccImj_firstThumb(get_the_content(), 60, get_permalink());
	the_title();
	the_excerpt();
}

1. Run a query to gather the posts we want to thumbnail

Using the wordpress standard post query statement to select 9 posts from the ‘Blog’ category.

query_posts( "category_name=Blog&showposts=10" );

2. Loop through all the posts returned by the query.

while(have_posts()) {
	the_post();
}

3. Get the first image from a post & create a thumbnail

Coming after the_post(), this function works in 3 steps, firstly it extracts the first image from within each post via get_the_content(). When it has the image it resizes it to 60 pixels square. Of course you can change this number to be what ever number you require. Lastly it wraps that thumbnail up in a link via get_permalink().

It is worth noting that the CC-ImageJuggler will work on any content that is passed to it. Practically this means it will work on any variable containing string data passed in the place of get_the_content(). Ultimately this means it isn’t necessary to be within ‘The Loop’ to function.

ccImj_firstThumb(get_the_content(), 60, get_permalink());

4. Add a little extra info

These standard wordpress functions add the title of the post and a little bit of the text content.

the_title();
the_excerpt();

Assuming that quite a few things are already in place, the above code should work first time without any difficulty. If you do encounter any problems please email us at support@choicecuts.com so that we can help you out, and in due course compile a meaningful FAQ.

Automatically resize all images within your Single post view

Currently this will require you to perform a few minor edits to cc_image_juggler.php, the plug-in file. We are well aware that this is far from ideal, and something we are looking into rectifying in the very near future.

The first task is to decide which of the FILTER FUNCTIONS, at the end of cc_image_juggler.php, is going to be used. Each function completes the resize process in a slightly different way, to achieve different results. Please note, you can only ever use one FILTER FUNCTION on your entire site at one time. Again this is something we intend to rectify.

ccImj_allFlexiWidth
Resize all images, to be within specified width sizes, in every post. If image is larger than max_width resize and present original via lightbox, or if smaller than min_width resize up to min_width.

ccImj_allWidth
Resize all images, to specified width, in every post to specified height and wrap it in a hyperlink if desired.

ccImj_allCrop
Resize all images, to specified square thumbnail size, in every post to specified height and wrap it in a hyperlink if desired.

When you have made your selection go to the top of the cc_image_juggler.php file and look for the series of 4 constants within the PLUGIN CONSTANTS & SETTINGS section. To activate your preferred FILTER FUNCTION change the FALSE value to TRUE. For example…

define('FILTER_FLEXI_WIDTH', TRUE);

The final step is to now adjust a couple of settings internal to the selected function. Each of the FILTER FUNCTIONS has a group of variables at their beginning which can be adjusted to configure them to your requirements. For example…

// TODO: variables I have yet...
$link_path = FALSE;
$min_width = 240;
$max_width = 510;

Hopefully you found this article to be useful. If you do use the ChoiceCuts Image Juggler in your theme or site please let us know. Likewise, if you want to use it and encounter a problem along the way drop us a line at support@choicecuts.com and we will be more than happy to help.