Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Images and image variations

How Exponential stores images and makes variations (aliases) - the shipped aliases, adding your own in image.ini, using them in templates, responsive images, converters, quality and clearing generated variations.

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/creators/website-creators/images-and-image-variations.md

On this page

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

  1. The shipped aliases
  2. Adding your own aliases
  3. Using aliases in templates
  4. Responsive images
  5. Converters, formats and quality
  6. After changing an alias
  7. Checklist

The shipped aliases

[AliasSettings] AliasList[] in settings/image.ini:

AliasRule
referencescaled down to fit 600 x 600; the base of the others
small100 x 100, from reference
tiny30 x 30
medium200 x 200
large300 x 300
rss88 x 31, for RSS feeds
originalthe 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;320

Name 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

SettingShippedMeaning
[ImageConverterSettings] ImageConverters[]GD, ImageMagickGD first (in PHP, no external program); ImageMagick for formats GD cannot read
[MIMETypeSettings] Quality[]image/jpeg;75JPEG quality
[MIMETypeSettings] ConversionRules[]WebP and GIF to PNG, everything else to JPEGthe output format of variations
[OutputSettings] AllowedOutputFormat[]JPEG, PNG, WebP, GIFthe formats pages may show
[ImageUploadSettings] AllowedMIMETypes[]JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP, SVGwhat 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-user

Then 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> has width, height and 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.

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x