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
Compression, image services and imported images
Images end to endPage 37 of 45Updated
What happens to an image's bytes between the file manager and the browser: lossy compression and its quality override, the image services that resize and convert, what happens when none can, and the setting that imports images pasted from other sites.
Who this is for. Site builders and developers choosing a site's image settings, or working out why an image is heavier or different than expected. After this page you can set compression from evidence, say which service handles which format, explain a WebP URL that serves a JPEG, and run a content migration with external image import safely.
Lossy compression
Lossy image optimization (key Files.images.minifyLossy, on by default) compresses delivered images with a lossy algorithm, which makes them considerably smaller. Override quality (key Files.images.minifyJpegQuality, empty by default) sets the JPEG and WebP quality, from 1 to 100; empty means the image service's own default.
Compression happens when an image is delivered, not on upload and not in the template. It applies to every resized or converted image, to every image changed since 22 February 2024, and to any request that names q or l in the URL. An older image that nothing has touched keeps its original bytes until it is resized, converted or replaced.
Judging the trade-off on real images
Decide on the site's own images rather than in the abstract. The URL parameters let you compare without changing a setting: request the same image with ?l=1&q=60, ?l=1&q=80 and ?l=0, compare the file sizes, and look at fine detail and flat colour, where compression shows first. A dozen images from the real site, photographs and graphics both, is enough to decide.
Shell
IMG="https://www.example.com/files/images/pages/hero.jpg"
for q in 60 80; do
curl -s -o /dev/null -w "q=$q %{size_download} bytes\n" "$IMG?l=1&q=$q"
done
curl -s -o /dev/null -w "lossless %{size_download} bytes\n" "$IMG?l=0"
The image services
Resizing, conversion and compression are done by external image services. Default image transformer (key Files.images.defaultTransformer) picks Kraken.io (kraken, the default) or Cloudinary (cloudinary) as the first choice for JPEG, PNG and GIF originals, with the other as the fallback. Some routing is fixed, whatever the setting says:
WebP goes through Cloudinary. Kraken neither reads nor writes WebP, so every conversion to WebP, and any work on a WebP original, is Cloudinary's.
SVG is handled by the platform itself. An SVG can be resized but never converted to another format, and there is no fallback.
Animated GIFs are not resized by Kraken, so their resizes go to the fallback.
Changing the setting therefore changes only which service handles JPEG, PNG and GIF first.
When no service can do the job
If no service can produce the requested version, because the service is unavailable or the request is one none of them supports, the platform delivers the original file unchanged under the requested URL. The request still succeeds and pages keep working, with heavier images. A .webp URL can therefore serve a JPEG; the response's Content-Type tells you which format arrived.
Importing images from other sites
When Import external images (key Files.images.importExternal, off by default) is on, saving a richtext area, in the admin or through the API, downloads every image embedded from another site into the file manager, at the same path it had on that site, and points the content at the local copy.
It exists for content migrations. Pasted content still hotlinks the old site's images, and those break when the old site is switched off; importing them on save keeps them. It brings three risks:
Copyright. Anything an editor pastes from anywhere is copied into the site, whether or not the site may use it.
Slow saves. Each image is fetched during the save, with up to five seconds allowed per image, so a long page of external images saves slowly the first time.
Path collisions. The copy is stored at the source path, and an existing file at that path is reused. Two sites that both have /images/logo.png end up sharing one file, so the second import shows the first site's logo too.
Switch it on for the migration, then off
Turn Import external images on while content is being migrated, check the imported files in the file manager, and turn it off again, so that later edits do not copy in whatever an editor pastes.