{img} · PAD tags

Syntax

{img 'photos/harbour.jpg', width=400, height=300, alt='text'}
{img 'photos/dunes.jpg', width=300, height=300, fit='contain', format='webp', quality=70, alt=''}

Parameters

file: The picture: a name below www/<application>/ - a JPEG, PNG, GIF or WebP.

Options

width: The width of the box in CSS pixels. With only one of width and height the picture keeps its proportion; with neither it keeps its size.
height: The height of the box in CSS pixels.
fit: cover (default: fill the box, cut around the centre) or contain (all of the picture inside the box).
format: jpeg, png or webp - default the source's, a GIF becoming a PNG.
quality: 1 to 100 for JPEG and WebP, default 80.
alt: Required: the text for whoever cannot see the picture. alt='' marks it as decoration.

Description

{img} shows a picture of www/<application>/ at the size the page needs, not the size the camera made. The first time a size is asked the picture is resized with GD (tags/_lib/img.php) and kept in www/<application>/_thumbs/, where the web server sends it like any other asset; every later request just writes the tag.

It writes <img class="pad-img"> with its width and height (no layout shift while it loads), loading="lazy", decoding="async" and a srcset whose second picture is twice the size for a sharp screen - as far as the source reaches, the density then said as it is (1.5x), and left out under 1.2x. A picture is never made larger than its source, and a JPEG is turned upright by its EXIF orientation. fit='cover' fills the box and cuts around the centre; fit='contain' keeps the whole picture.

The thumbnail's file name is a hash of the picture's contents and the options, so a changed picture gets a new address (safe behind a far-future cache header) and every machine makes the same names. It is written under a temporary name and renamed into place, so two requests never see half a file.

alt is required - a picture without it is read out by its file name; alt='' says it is decoration. A missing alt, a file that is not there or is no picture, an unknown fit or format and a quality outside 1-100 are errors under the strict check. A _thumbs/ directory the web server cannot write is an error too, and the original picture is written instead. While no picture exists yet, {placeholder} keeps its place.

Examples

Three pictures, one box

Landscape and portrait photos cut to the same 4:3 box around their centre, each with a 2x copy.

Templateexamples/img/1-cover.src

{img 'photos/harbour.jpg', width=176, height=132, alt='Sailing boats in the harbour at dawn'}
{img 'photos/dunes.jpg',   width=176, height=132, alt='Sand dunes under a pale sun'}
{img 'photos/tulips.jpg',  width=176, height=132, alt='Rows of tulips running to a windmill'}

The whole picture, as WebP

fit=contain keeps every pixel inside the box; format= and quality= choose the file that is made.

Templateexamples/img/2-contain.src

{img 'photos/dunes.jpg', width=260, height=260, fit='contain', format='webp', quality=70, alt='Sand dunes, the full portrait picture'}
{img 'photos/logo.png', width=48, alt=''}