Who this is for. Site builders setting up a site, and developers explaining why the same template renders images differently on two sites. After this page you know every image setting, its default and its effect, and have a starting combination for a new site.
The settings are in the admin with the Files settings and apply to the whole site. The names below are the labels the admin shows.
Every image setting
| Setting | Key | Default | What it changes | Normally changed? |
|---|---|---|---|---|
| Generate picture tag | Files.images.generatePictureTag | Off | Images rendered with getHtml() and images in richtext become a <picture> with a WebP source. More | Yes: on for most new sites |
| Offer hq image | Files.images.offerHqImage | On | Adds a 2x source when picture tags are on, the image was resized and the original is large enough. | Rarely |
| Show image placeholders | Files.images.usePlaceholder | For logged in users | What getAreaImageOrPlaceholder() gives for an empty area: Always, For logged in users or Never. More | Yes, to Never on sites with member accounts |
| Lossy image optimization | Files.images.minifyLossy | On | Lossy compression of delivered images. More | Rarely |
| Override quality | Files.images.minifyJpegQuality | Empty | JPEG and WebP quality, 1 to 100; empty uses the image service's default. | Only after comparing real images |
| Default image transformer | Files.images.defaultTransformer | Kraken.io | The first-choice service for JPEG, PNG and GIF; WebP and SVG are routed the same way whatever it says. More | Rarely |
| Import external images | Files.images.importExternal | Off | Images embedded from other sites in richtext are copied into the file manager on save. | During a content migration only |
| Add physical image size | Files.images.addPhysicalImageSize | Off | Images in richtext and image areas get a physical width and height. | Only for print output |
| Unit to use for physical size | Files.images.physicalSizeUnit | px | px, in or mm, for the setting above. | Only with physical sizes |
| DPI | Files.images.dpi | 500 | Dots per inch, for converting to inches or millimetres. | Only with physical sizes |
| Show dimensions in title tag | Files.images.showDimensionsInTitleTag | Off, per user | Adds an image's size to its title attribute, with physical sizes on. | By authors, for themselves |
| Show locations in title tag | Files.images.showLocationInTitleTag | Off, per user | Adds an image's file path to its title attribute, with physical sizes on. | By authors, for themselves |
| Add change time parameter to URL | Files.addTimeParameter | Off | Appends ?v= and a change-time value to every file URL. More | Yes, behind a third-party CDN or proxy |
| Default strategy for existing files | Files.defaultDuplicateStrategy | Use matching | What an upload with an existing file's name does. | Rarely |
| Default upload subfolder | Files.uploadFileSubfolder | ID based | The subfolder, and so the URL, of drag-and-drop uploads for a record. | Rarely |
| Default images/files folder | Files.defaultImagesFolder, Files.defaultFilesFolder | images, files | The top-level folder under /files/. | No |
| Use tags / categories for files | Files.useTags, Files.useCategories | Off, off | Nothing in the output; tags and categories on files in the file manager. | No |
Physical image size
Add physical image size gives images in richtext and image areas a physical width and height, in the unit set by Unit to use for physical size, calculated with DPI when the unit is inches or millimetres. It serves output destined for print, such as generated PDFs, where an image must come out at a set size on paper. Keep it off on a site that is only viewed on screens, because it writes fixed sizes into the markup.
Title-tag metadata
Show dimensions in title tag and Show locations in title tag put an image's size, its file path or both into its title attribute, so an author can hover over an image to check which file and size it is. Each user sets them for themselves, and they take effect only when Add physical image size is on. They are authoring aids, not features for visitors.
Upload behaviour
Default strategy for existing files decides what happens when an upload has the same name as an existing file:
- Use matching (the default) reuses the existing file if its contents are identical and renames the upload otherwise.
- Always rename keeps both.
- Update file adds the upload as a new revision of the existing file, so everything pointing at it shows the new image.
- Show error refuses the upload.
Default upload subfolder names the subfolder that drag-and-drop uploads for an existing record go into: after the record's id (ID based, the default) or after its slug. Either way it becomes part of the image's URL.
Add change time parameter to URL appends ?v= and a value derived from when the file last changed to every file URL, so a replaced image is fetched again even through a cache the platform does not control.
All three change what a template sees: which file a name resolves to, the folder in its path, and the query string on its URL. Images live under /files/images/ by default, in a folder per module, such as /files/images/pages/ and /files/images/blogs/.
A starting point for a new site
- Generate picture tag: on.
- Offer hq image: on.
- Show image placeholders: Never if the site has member accounts, otherwise the default.
- Lossy image optimization: on, with Override quality empty until you have compared real images.
- Add change time parameter to URL: on behind a third-party CDN or proxy, otherwise off.
- Default strategy for existing files: Use matching. Default upload subfolder: ID based.
- Everything else: the default.