diff --git a/wire/core/Pageimage.php b/wire/core/Pageimage.php index 6f4ef33e..4a4a3bf4 100644 --- a/wire/core/Pageimage.php +++ b/wire/core/Pageimage.php @@ -74,7 +74,7 @@ * @method Pageimage crop($x, $y, $width, $height, $options = array()) * @method array rebuildVariations($mode = 0, array $suffix = array(), array $options = array()) * @method install($filename) - * @method render($tpl = '') + * @method render($markup = '', $options = array()) * */ @@ -1654,7 +1654,7 @@ class Pageimage extends Pagefile { } /** - * Render markup for this image (optionally using a provided template string) + * Render markup for this image (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) @@ -1676,46 +1676,102 @@ class Pageimage extends Pagefile { * if($image) { * // default output * echo $image->render(); + * * // custom output - * echo $image->render("{alt}"); - * // custom output with link to original/full-size - * echo $image->render("{alt}"); + * echo $image->render("{alt}"); + * + * // custom output with options + * echo $image->render("{alt}", [ 'width' => 300 ]); + * + * // options can go in first argument if you prefer + * echo $image->render([ 'width' => 300, 'height' => 200 ]); + * + * // if only width/height are needed, they can also be specified as a string (1st or 2nd arg) + * echo $image->render('300x200'); + * + * // custom output with link to original/full-size and square crop of 300x300 for thumbnail + * echo $image->render([ + * 'markup' => "{alt}", + * 'width' => 300, + * 'height' => 300 + * ]); * } * ~~~~~ * - * @param string $tpl + * @param string|array $markup Markup template string or optional $options array if you do not want the template string here. + * @param array|string $options 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) + * - 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 string + * @see Pageimages::render() * */ - public function ___render($tpl = '') { - if(empty($tpl)) { - $tpl = "{description}"; + public function ___render($markup = '', $options = array()) { + + if(is_array($markup) || ($markup && strpos($markup, '}') === false)) { + $options = $markup; + $markup = isset($options['markup']) ? $options['markup'] : ''; + } + + if(empty($markup)) { + $markup = "{description}"; } + + if(is_string($options)) { + if(ctype_digit(str_ireplace('x', '', $options))) { + if(stripos($options, 'x') === false) $options .= 'x0'; + list($w, $h) = explode('x', strtolower($options)); + $options = array('width' => (int) $w, 'height' => (int) $h); + } else { + $options = array(); + } + } + /** @var Sanitizer $sanitizer */ $sanitizer = $this->wire('sanitizer'); + $image = $this; + $original = null; + $replacements = array(); $properties = array( - 'url', 'httpUrl', 'URL', 'HTTPURL', + 'url', 'httpUrl', 'URL', 'HTTPURL', 'description', 'alt', 'tags', 'ext', 'width', 'height', 'hidpiWidth', 'hidpiHeight', ); - $replacements = array(); + + if(!empty($options['width']) || !empty($options['height'])) { + $w = isset($options['width']) ? (int) $options['width'] : 0; + $h = isset($options['height']) ? (int) $options['height'] : 0; + $original = $this; + $image = $this->size($w, $h, $options); + } + + if(!empty($options['link']) && strpos($markup, 'entities1($this->get($property)); + if(strpos($markup, $tag) === false) continue; + $value = $sanitizer->entities1($image->get($property)); $replacements[$tag] = $value; } - if(strpos($tpl, '{original.') !== false) { - $original = $this->getOriginal(); - if(!$original) $original = $this; + + if(strpos($markup, '{original.') !== false) { + if(!$original) $original = $image->getOriginal(); + if(!$original) $original = $image; foreach($properties as $property) { $tag = '{original.' . $property . '}'; - if(strpos($tpl, $tag) === false) continue; + if(strpos($markup, $tag) === false) continue; $value = $sanitizer->entities1($original->get($property)); $replacements[$tag] = $value; } } - return str_replace(array_keys($replacements), array_values($replacements), $tpl); + + return str_replace(array_keys($replacements), array_values($replacements), $markup); } /** diff --git a/wire/core/Pageimages.php b/wire/core/Pageimages.php index 134adce9..c0c1f25c 100644 --- a/wire/core/Pageimages.php +++ b/wire/core/Pageimages.php @@ -25,8 +25,10 @@ * Typically a Pageimages object will be associated with a specific field attached to a Page. * There may be multiple instances of Pageimages attached to a given Page (depending on what fields are in it's fieldgroup). * - * ProcessWire 3.x, Copyright 2016 by Ryan Cramer + * ProcessWire 3.x, Copyright 2019 by Ryan Cramer * https://processwire.com + * + * @method string render($markup = '', $options = array()) * */ @@ -36,6 +38,9 @@ class Pageimages extends Pagefiles { * Per the WireArray interface, items must be of type Pagefile * * #pw-internal + * + * @param mixed $item + * @return bool * */ public function isValidItem($item) { @@ -46,7 +51,7 @@ class Pageimages extends Pagefiles { * Add a new Pageimage item, or create one from given filename and add it. * * @param Pageimage|string $item If item is a string (filename) then the Pageimage instance will be created automatically. - * @return $this + * @return Pageimages|Pagefiles * */ public function add($item) { @@ -164,4 +169,73 @@ class Pageimages extends Pagefiles { return $variations; } + + /** + * 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. + * + * ~~~~~ + * // default output + * echo $page->images->render(); + * + * // custom output + * echo $page->images->render("{alt}"); + * + * // custom output with options + * echo $page->images->render("{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 ""; + * ~~~~~ + * + * @param string|array $markup Markup template string or optional $options array if you do not want the template string here. + * @param array|string $options 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 string + * + */ + public function ___render($markup = '', $options = array()) { + $out = ''; + $limit = 0; + $n = 0; + if(isset($options['limit'])) { + $limit = (int) $options['limit']; + unset($options['limit']); + } + foreach($this as $image) { + $out .= $image->render($markup, $options); + if($limit > 0 && ++$n >= $limit) break; + } + return $out; + } }