NAME
App::Dapper::Images - Image sizes, responsive images and lazy loading.
DESCRIPTION
With images set in _config.yml, Dapper improves the images in every page it writes, after the site is built:
images: true
Dimensions. Each
<img>of a PNG, JPEG, GIF or WebP file in the site getswidthandheight, so the page doesn't jump about as images load.Lazy loading. Images after the first on a page get
loading="lazy", so the browser fetches them only as they scroll into view.Responsive sizes. JPEG and PNG images wider than a size in
sizesare resized to each smaller size (photo-480w.jpg,photo-960w.jpg, ...), and the<img>gets asrcsetlisting them, so phones download small files.WebP. With
webpon, a WebP copy of each size is made too, and the image is wrapped in a<picture>that offers it to browsers.
Every part can be set:
images:
dimensions: true # width and height (default: true)
lazy: true # loading="lazy" after the first image (default: true)
sizes: [480, 960, 1600] # widths to resize to (default; [] turns it off)
webp: true # WebP copies (default: true)
quality: 82 # JPEG and WebP quality (default: 82)
command: magick # magick, convert or vips (default: whichever is installed)
Resizing needs ImageMagick (magick or convert) or libvips (vips). Without one, Dapper says so once and does everything else. Resized images are kept in .dapper/images, so each is only made once. An image with a srcset of its own, or inside a <picture>, is left alone.
settings
Takes the site and returns the image settings as a hash reference, or nothing if images is not set.
process
Takes a Dapper object whose site has just been written, and improves the images in each HTML file it wrote.
image_tag
Takes the processing state, the attributes of an <img>, the directory of the page it is on, the site's address and whether it is the first image on the page. Returns the new HTML for it, or nothing to leave it alone.
variant_url
Takes an image URL, a width and (optionally) a new extension, and returns the URL of the resized copy: photo.jpg at 480 is photo-480w.jpg, and as WebP photo-480w.webp. Without a width, the full-size copy: photo.webp.
variants
Takes the processing state, an image in the output directory, its width and height, and the widths wanted. Makes each resized copy (and its WebP copy, if WebP is on) next to the image, and returns a list of hash references with the width and ext (same or webp) of each copy made. Returns nothing if no resizing command is installed.
command
Returns the command used to resize images (as an array reference), finding it the first time: the command setting, or magick, convert or vips, whichever is installed. Returns nothing, after one warning, if there is none.
resize
Takes the command (from "command"), an image, the file to write, the width and the quality, and resizes the image. Returns true if it worked.
image_size
Takes an image file (PNG, GIF, JPEG or WebP) and returns its width and height as it is displayed (so a JPEG turned by its EXIF orientation reports its turned size), or nothing if it can't tell.