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

Some of the resize functions above include an $options array. You can use the $options array like this:

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

You may specify any of the following for the $options array:

You may modify the default $options that your system uses by adding a $config->imageSizerOptions in your /site/config.php file:

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

Image properties

The above examples only refer to $image->url, but note that there are several other image properties you may wish to access.

For instance, $image->description refers to the description text entered for the image, which you may want to include as an alt attribute:

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

Here are all the image properties that are present with every image:

Using Image Tags

As of ProcessWire 2.3, multi-image fields support the option of specifying one or more tags for each image.

Tags make it easier to categorize and/or select specific images on the front-end of your site. You will see a checkbox to enable this option in your Image field settings. When enabled, a "tags" field will accompany each image in the page editor. When specifying more than one tag, each tag should be split by a space. Below are examples on how to retrieve images by tag on the front-end of your site. These examples assume your Images field is named 'images' and is set to contain more than 1 image.

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

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

When using getTag() the return value is a single PageImage or NULL if the tag is not found. When using findTag() the return value is a new Pageimages array, just like $page->images, but only containing the images matching the tag. If no matches were found, then it will be an empty Pageimages array.

The tags field is indexed and queryable from ProcessWire's database selector engine. Meaning, you can find pages based on what tags an images field contains. This is best demonstrated by examples:

// 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");