When a WordPress theme is heavily dependent on images, such as for thumbnails, featured post images and the like, it becomes heavily dependent on what the user uploads to use as those images. For instance, while the stylesheet might enforce 100 x 100 thumbnails, users often think nothing of uploading images directly from their 12 mega-pixel digital camera for those thumbnails.
A popular solution is the excellent timthumb library which re-scales and re-sizes images, caches the processed image so its immediately available the next time and feeds its output directly to the browser. The standard URL to timthumb looks like this:
path/timthumb.php?src=path-to-image.jpg&w=100&h=100&zc=1&q=80
Apart from the effort to generate the URL, the problem with this is that the browser can’t cache the resultant image and that the server has to run an instance of PHP simply to supply an image which is sitting in a cache, which is a huge waste of resources.
To solve these issues and to make timthumb more usable in a theme and for the end-user, I wrapped a plug-in called PostImage around the timthumb code, while adding some functionality. The plug-in is accessed using a [postthumb] shortcode which uses mostly the same parameters as a standard <img /> tag.
Once installed (see below), there is a new menu option under the Settings menu called Post Image which allows you to set its default values. The plug-in will use these default values unless you over-ride them in the shortcode, therefore set the values you will mostly use. Here are the values you can set:
Default Width: the width in pixels of the generated image. Equates to width=xxx in the shortcode.
Default Height: the height in pixels of the generated image. Equates to height=xxx in the shortcode.
NB: Setting height or width to 0 causes the image to be re-sized to the supplied dimension with the zero value dimension grown to suit the enforced dimension. See the next page for an example.
Default Quality: the default quality used to re-process the image, 100% is full quality. 80% generally results in a smaller image without noticeable image degradation. Equates to quality=xx in the shortcode.
Default re-size method: can be either crop or zoom. Crop (the default) chops off areas outside the center part of the image that fall outside the re-scaled image. Equates to crop=0 (zoom) or crop=1 (crop) in the shortcode.
Default image class: the class that gets applied to the image. Equates to class=xxxx in the shortcode.
Default image ID: the ID that gets applied to the image. Equates to id=xxxx in the shortcode.
Default image style: the default CSS styling that gets applied to the image, eg “float:left;margin-right=20px;”. Equates to style=”xxxx” in the shortcode.
Default post: The plug-in is designed to read data such as the source image file and its title from the current post. If PostImage is mainly used to process non-post related images, set to “No post”. See the next page for example usage. Equates to postid= in the shortcode.
Default custom key data: When the plug-in is using a post to determine the source image (the default) the key name of the custom field your theme uses to store the image; eg “Image” or “Thumbnail”. Equates to meta= in the shortcode.
Thickbox support: the plug-in can return a Thickbox link so that the re-sized image can be clicked to display the larger image in a Thickbox overlay. The plug-in will link in the jQuery and Thickbox javascript files to either all pages if set to “Always”, or just single posts and pages if set to “Single Posts/Pages”. Equates to thickbox=x in the shortcode (any non-zero value means a link is generated, a zero value means no link is generated).
THICKBOX NOTES:
- In typical usage where PostImage is being used to generate thumbnails on index pages, the thumbnail will be linked to the post and enabling Thickbox support Always will lead to invalid embedded links and not produce the expected result. Either don’t set thickbox support to Always, or disable thickbox links in the shortcode using thickbox=0.
- Thickbox support must be enabled in settings – either Always or Single Posts/Pages – for the jQuery and thickbox scripts to be linked into the header. Just enabling thickbox in the shortcode (eg thickbox=1) WILL NOT cause these scripts to be loaded and hence allow thickbox to work correctly.
- Setting thickbox=1 in the postimage shortcode when thickbox support is “None” in settings will generate a link to the raw image that will open in a new tab.
- The Thickbox CSS is also linked in when in use. For optimal performance, copy the contents of wp-includes/js/thickbox/thickbox.css into your main stylesheet (ie style.css) and delete “wp_enqueue_style(‘thickbox’);” near the bottom of postimage.php.
The Image Cache
All re-processed images are cached in a sub-directory called “cache” in the postimage directory (ie; wp-content/plugins/postimage/cache) for subsequent retrieval. When saving settings, PostImage will attempt to create the cache directory if it doesn’t exist and save a file in it. A cache success or failure message will be displayed. You will usually have to create the directory manually and/or set its permissions to everybody can read/write (ie 0777) using your FTP client.
PostImage Shortcode Usage
To use just the default settings and retrieve an image from the current post, simply use [postimage]. Additional parameters are passed in the standard format. Values with spaces need to be enclosed in quotes. Eg; [postimage width=100 title="The Image Title" /].
As mentioned above, the standard usage of this plug-in is to retrieve the location of the source image from custom post data, using the key saved in settings. If there is no custom data, the plug-in will retrieve the first image in the content of the post. You can also specify an image in the shortcode to be used instead of accessing any post.
The plug-in can be used directly in your source code files, eg <?php [postimage] ?> or within the content of posts and pages.
If the plug-in can’t find a source image it will not return anything.
All the accepted shortcode parameters are as follows:
| alt | The image alternative text. Uses the post or page title if one has been set. |
| class | The name of a CSS class to be set for the new image. |
| crop | Set to 1 to crop the image to fit the new dimensions, or set to 0 to force the entire image to be re-proportioned to fit the new dimensions. |
| height | Height of the new image in pixels. Set to 0 to have the height re-sized to suit the new width. |
| id | The name of a CSS ID to be set for the new image. |
| image | Path to an image, either a full URL or a relative reference. The image must be on the current domain. |
| meta | The name of the post/page custom data key holding the location of an image. |
| postid | The ID of the post or page from which to pull data. Set to -1 to use the current post (“Current post” in default settings), or 0 to not use a post (“No post in default settings). |
| quality | Set from 0 to 100, with 100 being the highest quality. |
| rel | The “rel” attribute of the thickbox link around the image. Used for grouping images with thickbox. |
| style | CSS styling to be applied directly to the image. |
| thickbox | Set to a non-zero value to enclose the new image in a link to the source image, with the class of the <a> tag set to “thickbox”. Thickbox support must be enabled in settings (or otherwise in use with your theme) for the original image to be displayed in an overlay, otherwise the original image will open in a new browser tab. |
| title | The image title. Uses the post or page title if a post or page is available (either the current one, or one pointed to by postid). |
| width | Width of the new image in pixels. Set to 0 to have the width re-sized to suit the new height. |
PostImage Installation
Download postimage.zip, extract and upload the postimage directory to your WordPress plug-ins folder. While you’re still logged into your site via FTP, set the permissions on postimage/cache sub-directory as previously described. Activate the plug-in and then go to the settings page. Save the settings even if you make no changes to the defaults to test the operation of the cache.
There are some examples of usage on the next page.
