Images and image aliases #

This page is for developers who decide where images live in the content model and in which sizes the site shows them. Exponential stores the original once and makes every size on demand from named image aliases, so a redesign changes settings, not uploads.

Contents #

1. Image attribute or image object
2. The media library
3. Image aliases
4. Defining an alias for your design
5. Images in templates
6. Alternative text
7. Focal point and crop
8. Converters: GD and ImageMagick
9. After a change

Image attribute or image object #

Image objects have their own name, caption and alternative text, appear in the media library and carry their own permissions. Choosing between the two is one of the decisions in Choosing datatypes.

The media library #

The media library is the subtree below node 43 (settings/content.ini [NodeSettings] MediaRootNode), in the section Media. Images and files placed there are not part of the site's navigation. The Anonymous role of a new installation reads only the section Standard (Sections), so check your roles when visitors must open media objects directly. Organize the library in folders by topic or by site, not by date. Uploading in bulk is covered by the upload page of ezmultiupload (Media and uploads).

Image aliases #

An alias is a named size and treatment, defined in image.ini. The shipped list ([AliasSettings] AliasList[]) is reference, small, tiny, medium, large and rss:

[reference]
Filters[]
Filters[]=geometry/scaledownonly=600;600

[medium]
Reference=reference
Filters[]=geometry/scaledownonly=200;200

Reference names the alias the scaling starts from (here the 600 pixel reference, rather than a camera original), and Filters[] lists the operations in order. scaledownonly never enlarges a small image. Every alias is created the first time a page asks for it and kept as a file in the storage directory.

Defining an alias for your design #

Put your aliases in your design extension, prefixed with its name so they never clash with shipped ones:

# extension/exp_mysite/settings/image.ini.append.php
<?php /* #?ini charset="utf-8"?

[AliasSettings]
AliasList[]=exp_mysite_card
AliasList[]=exp_mysite_hero

[exp_mysite_card]
Reference=reference
Filters[]=geometry/scaledownonly=480;320

[exp_mysite_hero]
Filters[]=geometry/scaledownonly=1600;900
*/ ?>

The hero alias has no Reference, so it scales from the original: a hero larger than 600 pixels must not start from reference. Designers have the same recipe with responsive output: Image aliases.

Images in templates #

The datatype template prints a complete <img> for an alias:

{attribute_view_gui attribute=$node.data_map.image image_class='exp_mysite_card'}

For your own markup, read the alias from the attribute's content:

{def $img = $node.data_map.image.content['exp_mysite_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, so the page does not jump while images load (Image performance). Every alias a page names is created on first use, so do not name aliases you do not show.

Alternative text #

An ezimage attribute stores an alternative text with the image. A class can make it required: tick Alternative text is required on the image attribute in the class editor; editors then cannot store an image without one. Imports and bulk uploads do not ask for it, so fill it afterwards (Alternative text is required). A decorative image gets an empty alt, deliberately, in the template.

Focal point and crop #

An image can carry a focal point and a crop rectangle, per attribute version (fractions of the original, stored in the attribute's XML). The crop rectangle is cut out before an alias's filters, and every geometry/crop filter puts its window around the focal point instead of at its own x;y, so a scale-and-crop alias keeps what matters in the picture. Images without them are converted exactly as before. Templates read focal_point (with position, ready for CSS object-position) and crop_rectangle. Code sets them with setFocalPoint() on a draft, which drops the aliases made so far. Details: Image focal point and crop.

Converters: GD and ImageMagick #

image.ini [ImageConverterSettings] ImageConverters[] lists the converters in order: GD (the PHP extension) and ImageMagick (the convert program). The Composer metadata of Exponential says GD is required unless ImageMagick is installed. On a host, check which is present before you rely on filters that only one of them supports (Image processing and media).

After a change #

Changing the filters of an existing alias does not recreate the files already made. Clear them, and the INI cache for a new or changed alias:

php bin/php/ezcache.php --clear-tag=ini --allow-root-user
php bin/php/ezcache.php --clear-id=imagealias --allow-root-user

The first visits afterwards are slower while the scaled files are made again; on a large site do it in a quiet hour.

Related pages #

• Relations and embeds
• Images in a design
• Caching for CMS developers
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.