Images and image variations
This page is for website creators who decide how images appear on a site. An editor uploads one image; the site shows
it in several sizes, called aliases (variations), generated on first use from rules in settings/image.ini
(10.8 Images).
Contents
- The shipped aliases
- Adding your own aliases
- Using aliases in templates
- Responsive images
- Converters, formats and quality
- After changing an alias
- Checklist
The shipped aliases
[AliasSettings] AliasList[] in settings/image.ini:
| Alias | Rule |
|---|---|
reference | scaled down to fit 600 x 600; the base of the others |
small | 100 x 100, from reference |
tiny | 30 x 30 |
medium | 200 x 200 |
large | 300 x 300 |
rss | 88 x 31, for RSS feeds |
original | the uploaded file itself |
scaledownonly never enlarges a small image. Themes add their own aliases in their image.ini.append.php.
Adding your own aliases
In your design extension:
# extension/mysite_design/settings/image.ini.append.php
[AliasSettings]
AliasList[]=hero
AliasList[]=card
[hero]
Reference=
Filters[]
Filters[]=geometry/scalewidthdownonly=1600
[card]
Reference=reference
Filters[]
Filters[]=geometry/scaledownonly=480;320Name aliases after their purpose (hero, card), not their size: when the design changes, the size changes and the
name still fits. The filters available depend on the converter; settings/image.ini lists them in the [GD] and
[ImageMagick] blocks.
Using aliases in templates
{attribute_view_gui attribute=$node.data_map.image image_class='card'}renders the image field with the card alias and its alternative text. For your own markup, read the alias:
{def $img = $node.data_map.image.content['card']}
<img src={$img.url|ezroot} width="{$img.width}" height="{$img.height}" alt="{$img.alternative_text|wash}" loading="lazy">
{undef $img}Always print width and height (the page does not jump while images load) and the alternative text. Image fields can
require an alternative text (The content model and editing).
Responsive images
Define two or three aliases of the same image and offer them with srcset:
{def $c = $node.data_map.image.content}
<img src={$c['card'].url|ezroot}
srcset="{$c['card'].url|ezroot(no)} {$c['card'].width}w, {$c['hero'].url|ezroot(no)} {$c['hero'].width}w"
sizes="(min-width: 960px) 50vw, 100vw"
width="{$c['card'].width}" height="{$c['card'].height}" alt="{$c.alternative_text|wash}">
{undef $c}Converters, formats and quality
| Setting | Shipped | Meaning |
|---|---|---|
[ImageConverterSettings] ImageConverters[] | GD, ImageMagick | GD first (in PHP, no external program); ImageMagick for formats GD cannot read |
[MIMETypeSettings] Quality[] | image/jpeg;75 | JPEG quality |
[MIMETypeSettings] ConversionRules[] | WebP and GIF to PNG, everything else to JPEG | the output format of variations |
[OutputSettings] AllowedOutputFormat[] | JPEG, PNG, WebP, GIF | the formats pages may show |
[ImageUploadSettings] AllowedMIMETypes[] | JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP, SVG | what editors may upload |
SVG is handled differently: it is sanitized and never scaled (SVG and image formats).
After changing an alias
Generated variations stay until removed:
php bin/php/cache.php imagealias clear --allow-root-userThen clear the content view cache so pages link the new files.
Checklist
- To do: One alias per image role of the design, named by purpose.
- To do: Every
<img>haswidth,heightand alternative text. - To do: Large images use
loading="lazy"below the fold. - To do: JPEG quality and output formats chosen consciously.
- To do: Old variations cleared after an alias change.
Related pages
- Organizing the media library
- Media and uploads (for editors)
- Velocity: static files and images
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.