Pageimages::render() method

Render markup for all images here (optionally using a provided markup template string and/or image size options)

Given template string can contain any of the placeholders, which will be replaced:

  • {url} or {src} Image URL (typically used for src attribute)
  • {httpUrl} File URL with scheme and hostname (alternate for src attribute)
  • {URL} Same as url but with cache busting query string
  • {HTTPURL} Same as httpUrl but with cache busting query string
  • {description} or {alt} Image description (typically used in alt attribute)
  • {tags} File tags (might be useful in class attribute)
  • {width} Width of image
  • {height} Height of image
  • {hidpiWidth} HiDPI width of image
  • {hidpiHeight} HiDPI height of image
  • {ext} File extension
  • {original.name} Replace “name” with any of the properties above to refer to original/full-size image. If there is no original image then these just refer back to the current image.

Available since version 3.0.126.

Example

// default output
echo $page->images->render();

// custom output
echo $page->images->render("<img class='pw-image' src='{url}' alt='{alt}'>");

// custom output with options
echo $page->images->render("<img src='{url}' alt='{alt}'>", [ 'width' => 300 ]);

// options can go in first argument if you prefer
echo $page->images->render([ 'width' => 300, 'height' => 200 ]);

// if only width/height are needed, they can also be specified as a string (1st or 2nd arg)
echo $page->images->render('300x200');

// custom output with link to original/full-size and square crop of 300x300 for thumbnails
echo "<ul>" . $page->images->render([
  'markup' => "<li><a href='{original.url}'><img src='{url}' alt='{alt}'></a></li>",
  'width' => 300,
  'height' => 300
]) . "</ul>";

Usage

// basic usage
$string = $pageimages->render();

// usage with all arguments
$string = $pageimages->render($markup = '', $options = []);

Arguments

NameType(s)Description
markup (optional)string, array

Markup template string or optional $options array if you do not want the template string here.

options (optional)array, string

Optionally resize image with these options sent to size() method:

  • width (int): Target width or 0 for current image size (or proportional if height specified).
  • height (int): Target height or 0 for current image size (or proportional if width specified).
  • markup (string): Markup template string (same as $markup argument), or omit for default (same as $markup argument).
  • link (bool): Link image to original size? Though you may prefer to do this with your own $markup (see examples). (default=false)
  • limit (int): Render no more than this many images (default=0, no limit).
  • Plus any option available to the $options argument on the Pageimage::size() method.
  • If you only need width and/or height, you can specify a width x height string, i.e. 123x456 (use 0 for proportional).

Return value

string


Hooking Pageimages::render(…)

You can add your own hook events that are executed either before or after the Pageimages::render(…) method is executed. Examples of both are included below. A good place for hook code such as this is in your /site/ready.php file.

Hooking before

The 'before' hooks are called immediately before each Pageimages::render(…) method call is executed. This type of hook is especially useful for modifying arguments before they are sent to the method.

$this->addHookBefore('Pageimages::render', function(HookEvent $event) {
  // Get the object the event occurred on, if needed
  $Pageimages = $event->object;

  // Get values of arguments sent to hook (and optionally modify them)
  $markup = $event->arguments(0);
  $options = $event->arguments(1);

  /* Your code here, perhaps modifying arguments */

  // Populate back arguments (if you have modified them)
  $event->arguments(0, $markup);
  $event->arguments(1, $options);
});

Hooking after

The 'after' hooks are called immediately after each Pageimages::render(…) method call is executed. This type of hook is especially useful for modifying the value that was returned by the method call.

$this->addHookAfter('Pageimages::render', function(HookEvent $event) {
  // Get the object the event occurred on, if needed
  $Pageimages = $event->object;

  // An 'after' hook can retrieve and/or modify the return value
  $return = $event->return;

  // Get values of arguments sent to hook (if needed)
  $markup = $event->arguments(0);
  $options = $event->arguments(1);

  /* Your code here, perhaps modifying the return value */

  // Populate back return value, if you have modified it
  $event->return = $return;
});

Pageimages methods and properties

API reference based on ProcessWire core version 3.0.184

Twitter updates

  • ProcessWire 3.0.185 (dev) core updates, plus new Session Allow module— More
    17 September 2021
  • Three new ProcessWire Textformatter modules: Find/Replace, Markdown in Markup, and Emoji— More
    3 September 2021
  • This week we have a new master version released after a year in the making. With nearly 40 pull requests, hundreds of new additions and more than 100 issue reports resolved, this new version has a ton of great new stuff— More
    27 August 2021

Latest news

  • ProcessWire Weekly #384
    In the 384th issue of ProcessWire Weekly we'll cover the latest core updates, introduce a new module called Session Allow, and highlight a new site of the week. Read on!
    Weekly.pw / 18 September 2021
  • ProcessWire 3.0.184 new master/main version
    This week we have a new master/main version released after a full year in the making. As you might imagine, this new version has a ton of great new stuff and we’ll try to cover much of it here.
    Blog / 27 August 2021
  • Subscribe to weekly ProcessWire news

“…building with ProcessWire was a breeze, I really love all the flexibility the system provides. I can’t imagine using any other CMS in the future.” —Thomas Aull