FieldtypeImage (for images fields)

This page outlines using and manipulating image fields — one of the most commonly used in ProcessWire.

To interact with the images field. Create a new field (under Setup > Fields) and call it whatever you want, like "images" for example. Set the field type as "image". Save. On the details tab, you may set the maximum quantity of images the field may contain. Please note that if you set it to one (1), the field will usually behave as a single image rather than an array of images, and this affects how you access it from the API. Add this new images field to a template (under Setup > Templates). Then edit a page using that template and upload some images.

How to access the images field from your templates

In your template files, you can loop through the images field and output each image:

foreach($page->images as $image) {
 echo "<img src='$image->url'>";
}

If you set your images field to contain just 1 image, then the above wouldn't work because $page->images (which you would probably name $page->image, singular, instead) refers to just a single image.* Instead, you would do something like this:

if($page->image) echo "<img src='{$page->image->url}'>";

*Note for advanced users: the single image behavior described above is only applicable when output formatting is ON, as it is by default in template files. When output formatting is OFF, image fields always behave as arrays.

When your image field is set to contain more than one image, $page->images is a WireArray. You may use any of the functions provided by WireArray. For example:

// grab and output first image
$image = $page->images->first();
if($image) echo "<img src='$image->url'>";
// grab and output a random image
$image = $page->images->getRandom();
if($image) echo "<img src='$image->url'>";

How to tell if a page has images present

It is a good idea to check if an image(s) field has something in it before attempting to output it. When set to contain multiple images, you can tell if a page contains one or more images by using the count() function:

if(count($page->images)) {
 // the page has one or more images
}

When set to contain a max of one (1) image, then you can just check if your image field has a value:

if($page->image) {
 // an image is present
}

Resizing images

ProcessWire will create your images at any size on the fly and then keep a cache of them.

For instance, lets say we want to cycle through all the images, create a large image at 500 pixel width with proportional height, and a thumbnail at 100x100, and then have the thumbnail link to the large:

foreach($page->images as $image) {
 $large = $image->width(500);
 $thumb = $image->size(100, 100);
 echo "<a href='$large->url'><img src='$thumb->url'></a>";
}

Note that when sizing an image, a new copy is created and cached, so that it doesn't have to be re-created every time. The table below shows all available image resize functions:

Image resize functions

$options = array(
 'quality' => 90,
 'upscaling' => false,
 'cropping' => 'southeast'
);
$img = $image->size($x, $y, $options);

$config->imageSizerOptions = array(
 'upscaling' => true,
 'cropping' => true,
 'quality' => 90,
 );

echo "<img src='$image->url' alt='$image->description' />";

// retrieve first image with tag 'mytag'
$image = $page->images->getTag('mytag');
// retrieve all images with tag 'mytag'
$images = $page->images->findTag('mytag');

// Find pages containing an image with the single (1) tag: sport
// This will only match images with 1 single tag of "sport".
$mypages = $pages->find("images.tags=sport");
// Find pages containing an image with at least tag: sport
// This will match "sport" but not "sports".
$mypages = $pages->find("images.tags~=sport");
// Find pages containing images with tags starting with: sport
// This will match: sport, sports, sportscar, etc.
$mypages = $pages->find("images.tags*=sport");
// Find pages containing images with partial tag match for: port
// This will match: port, sport, sports, sportscar, report, etc.
$mypages = $pages->find("images.tags%=port");