Guide 04 · Developer docs

Input types, layouts, components and images

The platform's central abstraction, in one line: an input type defines what an editor can enter, a layout area binds one input type to a named slot, a layout groups areas and points at a template, a record or component holds the content for each area, and the template reads it back. Read this book straight after the template languages.

L1–L3
Unit 08 · Images end to end

The image object

Images end to end Page 32 of 45 Updated

What the image object tells you (dimensions, format, name and path), how to reserve space with its aspect ratio, the shape of the URL it builds, and the two methods that exist on it but are not available to templates.

Who this is for. Developers who have an image from an area and need its facts: size, format, name and URL. After this page you can reserve layout space before an image loads, build an absolute image URL where one is needed, and know which of the object's methods a template can call.

Three objects, one set of methods

A template can hold three kinds of image object, and all three answer the same methods:

  • the image itself, straight from an area and not yet resized;
  • a blank image, from an empty area (see From an image area to an image);
  • a transformed image, which getResized(), toFormat() and toOptimizedFormat() return.

That is why a chain such as {$page->heroImage->getResized(800, 450, 'fit')->getHtml()} works whichever object each step happens to be, and why every method below can be called on a resized image as well as an original.

Dimensions, format and name

MethodReturns
getWidth(), getHeight()The pixel dimensions. After getResized(), the resized dimensions.
getAspectRatio()Width divided by height: 2.0 for a 480 × 240 image.
getFormat()jpeg, png, gif, webp or svg, worked out from the file's MIME type, not from the extension in its name.
getMimeType()The full MIME type, such as image/png.
getName()The image's name in the file manager. getHtml() uses it as the default alt text.

In Twig the same values read as properties: image.width, image.height, image.name.

Reserving space with the aspect ratio

An image with no dimensions takes no space until it loads, and the content below it jumps when it arrives. Give its container the image's proportions, so the browser reserves the space from the start:

Template code 
{$image = $component->photo}
<div class="media" style="aspect-ratio: {$image->getWidth()} / {$image->getHeight()}">
  {$image->getHtml(['alt' => $image->getName()|escape, 'loading' => 'lazy'])}
</div>
{% set image = component.photo %}
<div class="media" style="aspect-ratio: {{ image.width }} / {{ image.height }}">
  {{ image.getHtml({'alt': image.name|e, 'loading': 'lazy'}) }}
</div>

A resized image rendered with getHtml() gets width and height attributes of its own, which does the same job; see Resizing, converting and rendering an image.

The path, and absolute URLs

getPath() returns the URL the browser fetches: the platform's file route, /files/, followed by the image's folder and file name in the file manager, for example /files/images/api-sandbox/api-sandbox-figure.png. A transformed image's path carries the transformation as query parameters, described on Image URL parameters.

The path is relative to the site: it starts with / and has no scheme or host. getFullPath() returns exactly the same string; despite its name, it is not an absolute URL. Where an absolute URL is needed, such as an og:image tag or an email, put the site's own address in front of the path: $_currentSite->getPrimaryEnvironmentPrimaryHostname() in Smarty, _currentSite.primaryEnvironmentPrimaryHostname in Twig, gives the hostname with no scheme to put in front of it.

The change-time parameter

When the setting Add change time parameter to URL (key Files.addTimeParameter, off by default) is on, every path ends in ?v= and a short value derived from when the file was last modified. Replacing the file changes the value and so the URL, which makes a cache the platform does not control, such as a third-party CDN or proxy in front of the site, fetch the new file instead of serving the old one. With the setting off, no v is added.

Two methods a template cannot call

getTransformed() is the low-level call the convenience methods are built on: getResized(), toFormat() and toOptimizedFormat() each build a transformation and pass it to getTransformed(). It is withheld from templates, so $image->getTransformed(…) fails in Smarty and Twig with Method getTransformed does not exist in …. A template does not need it: everything it does is reachable through those three methods or the URL parameters. It belongs to backend PHP code that works with the image record itself.

clearCache() clears the CDN cache for the image's path and for its record. It is not available to templates either, and it is rarely needed anywhere: when the file behind an image is replaced in the file manager, the platform clears that image's cache by itself. It exists for backend PHP code that changes image records directly.

Go deeper
GuideFrom an image area to an image GuideResizing, converting and rendering an image GuideImage URL parameters GuideImage settings

Was this page helpful?

Your answer goes to the docs team.