> > > Using the resizer

Using the image resizer

Overview

The resizer is a script which takes an image on the server, one you might have uploaded for instance, and processes it so that it can be displayed on your site at whatever size you want. You tell the resizer what to do at the template level, so it's possible to display the same image at different sizes; as a thumbnail in a gallery page, perhaps, and again much larger when the user clicks on the thumbnail.

This means, within certain limitations, that you don't have to resize images yourself, or upload separate thumbnail and full size versions, although it's still possible to do this if you need to.

The resizer is very flexible, and can also be used to alter the proportions of an image, as well as crop, and to combine these effects.

The script saves the resulting resized image so that, next time, it can simply use the saved version, which is much faster than generating a resized image every time.

What follows is a description of how to use the resizer, and some of it is necessarily quite technical. You won't need to read any of this simply in order to use Content Curator, but we provide this information for those who are interested.

Parameters

The resizer accepts a number parameters sent in the query string.

croptype
Set to 'top', 'bottom', 'left', 'right' or 'centre'; it won't have any effect unless fittodimensions is set to 'crop'. The effects are currently outside the scope of this documentation.
file
Path to the image file to resize, relative to the resizer script.
width
Target width for the resized image, in pixels.
height
Target height for the resized image, in pixels.
enlarge
Set to 'true' or 'false'. If it's not set, the script assumes it's true. If you set it to false then the script won't resize an image which is smaller than the size you have specified.
fittodimensions
Set to 'fit', 'fill' or 'crop'. It's a way of constraining height and width at the same time, while retaining aspect ratio. See under fittodimensions below for details.
preset
If you want images in more than one context throughout the site to appear with the same settings, then it sometimes makes sense to save the parameters to a file, and then set only the preset parameter in each template to reference that file. We don't expect users of the system to do that themselves, but of course you're welcome to. Get in touch for more details if you want to do this.
proportional
Set to 'true' or 'false'. Controls whether or not the aspect ratio of the image is retained. See under proportional below for details.
outputdirectory
Path to the directory where the resized image will be cached, relative to the resizer script.

'proportional'

Suppose you want to restrict the width of an image to 150 pixels and allow the height to change proportionally. In that case, set width to '150', height to '0' and proportional to 'true'.

You can do the same thing the other way round, resizing proportionally to a fixed height, by specifying height and setting width to '0'.

You might want to resize to a fixed width and height, stretching and squeezing the image to fit its new proportions irrespective of its original aspect ratio, in which case set width and height to the desired pixel sizes, and set proportional to 'false'.

'fittodimensions'

An image showing the effect of the different 'fittodimensions' options on a resized image

fig. 1

This parameter resizes the image with respect to an imaginary box, the dimensions of which are set by the width and height parameters.

If it's set to 'fit' then the image is resized to fit entirely within the imaginary box; if set to 'fill' then it will entirely fill the box, even though that will probably create some overlap. Of course, if the aspect ratio of the image is the same as that of the imaginary box then 'fit' and 'fill' will produce the same result!

To help you use this, fig. 1 simulates what will happen to two images, one portrait and one landscape. In each case width has been set to '150' and height to '100'. This is marked on the example images with a red box, but of course in real life there is no red box. On the left, fittodimensions is set to 'fit', and on the right to 'fill'.

If this parameter is set, the resizer script assumes that proportional is set to 'true'.

N.B.: It's also possible to set this parameter to 'crop', in which case croptype should also be set. The effects of this are currently outside the scope of this documentation.

Simple cropping

Instead of setting fittodimensions to 'crop' and using the croptype parameter, it's often easier for many purposes to set fittodimensions to 'fill', and place the image within a fixed-size div styled as 'overflow:hidden;'

Example

Here is an example of the resizer in action. The following code in the listing template of, say, a gallery, will display a thumbnail for each image and, when the user clicks that, a pop-up window with a much larger version of it.


<a href="./public_scripts/resizer.php?file=../{{MEDIA_DIR}}{{PLAIN_IMAGE}}&width=700px&height=500&fittodimensions=fit&outputdirectory=../{{MEDIA_DIR}}cache" class="thickbox" rel="gallery" title="{{DESCRIPTION}}">
    <img src="./public_scripts/resizer.php?file=../{{MEDIA_DIR}}{{PLAIN_IMAGE}}&width=150px&height=0&proportional=true&outputdirectory=../{{MEDIA_DIR}}cache" alt="{{CAPTION}}" />
</a>

(Note that not every aspect of this code will work on every site without some configuration.)

Limitations

There is a limit to the size of an image which the resizer can work on without crashing. It's hard to specify this precisely because it depends on neither the file size nor the pixel size of the image, but on the amount of the server's memory needed to operate on it; as a rule of thumb, however, a JPEG image shouldn't be larger than around 3.5Mb on disk.

The only image types with good cross-browser support are JPEG, GIF and, to a lesser extent, PNG. This isn't a limitation of the resizer per se, but Content Curator doesn't support its use with any other image types.

The resizer uses PHP's GD image manipulation library, and consequently represents a subset of GD's capabilities. See here for GD documentation.