Image variants#

How large the resized copies are that get made from an image somebody uploads — for an article, a product, an advert, a category and so on. Find it under Nastavení → Varianty obrázků (image variants; the Nastavení link at the very bottom of the left column, see Settings).

When an image is uploaded it is stored and the system immediately makes resized copies of it. How large, in which resize mode and whether with a watermark is exactly what the variants say.

What a variant is#

A variant = a named recipe for one resized copy. It consists of four things:

Item	What it means
Max. šířka (px) and Max. výška (px) (max. width and height)	the size the image is shrunk to; width 1–8000 px, height 0–8000 px (a height of 0 = a width-only variant)
Režim zmenšení (resize mode)	Poměrově (nezvětšuje) (proportional, never enlarges) — the image fits into the size and is never enlarged; Ořez na přesný rozměr (crop to exact size) — fills the exact size and the overflow is cut off
Vodoznak (watermark)	a watermark is drawn into the variant (the `watermark.png` file of the System module)
Aktivní (active)	an inactive variant is not made for new images, even when assigned

A variant does not say for which images it is made. That is assigned separately, for each usage of an image — see Where variants are assigned below.

Every extra variant costs space and time

It takes disk space for every new image it is assigned to and makes uploads slower. Add only the variants the template really uses.

The list of variants#

The Varianty (variants) tab shows all variants: Název (name), Rozměr (size), Režim (mode), Vodoznak, Aktivní, how many Použití (usages) it has, and Pořadí (order).

Adding and editing#

Click add and fill in the Název, the sizes and the Režim zmenšení.
Tick Vodoznak if you want one.
Save.

The Název is a technical key: lowercase letters, digits and a hyphen (e.g. 1600x1200, at most 32 characters). The names original, big and thumb are reserved.

A variant's name cannot be changed after creation

For a usage without an alias the name is also the folder name on disk. If it changed, it would no longer match the folders of images already stored. Think the name through beforehand.

Two variants with the same size, mode and watermark cannot be created — the system tells you which identical one already exists.

A width-only variant#

If you enter a height of 0, the variant goes by width alone: the image is shrunk to that width, the height follows from the aspect ratio (and a smaller image is not enlarged). It suits places where only the width of the image matters and the height should simply adapt.

Name such a variant after its width, e.g. w1600 (a variant 1600 px wide).
The resize mode must be Poměrově (proportional). Ořez na přesný rozměr (crop to exact size) needs a height — with a height of 0 the system does not save it and tells you to choose proportional resizing.
In the list of variants the size is shown as "šířka 1600 px" (width 1600 px).

A change of size applies only to newly uploaded images

Already stored images keep their current files and keep working (missing resized copies can optionally be regenerated). If you need a different size only for some usage, create a new variant instead and assign it to that usage. The form lists the usages the variant is in when you edit it.

Deleting and turning off#

A variant that is used in any usage cannot be deleted. The system lists where it is used; remove it from those usages first.
A variant that carries a required alias in any usage (for example big, thumb or icon32, see Required aliases) cannot be turned off (unticking Aktivní). The usage cannot work without it; the system tells you which usage is affected.

Where variants are assigned#

Each module has images in several places — the blog, for instance, on an article, a category and a gallery. Each such place is called a usage, and for each one you decide separately which variants are made.

The Použití tab#

The Použití (usages) tab (next to the Varianty tab) shows all usages of all modules in one place: System, Blog, E-shop, Classifieds, Company catalogue, Discussion and Company. The usages are grouped by module and each module has its own form with its own Save images button — so you always save only the module you edited. The Company module has no settings page of its own, so its images (logo, photo and gallery, references, price list group, team member, category) are set only here. The same goes for the images of the System module.

The modules that do have a settings page (Blog, E-shop, Classifieds, Company catalogue, Discussion) have the same thing in their own settings, on the Images tab — always with that module's usages only. The tab has its own Save images button. See the settings of the modules Blog, E-shop, Classifieds, Company directory and Discussion.

What is set for a usage#

For each usage (e.g. Blog — article and news, E-shop — product (main photo), Classifieds — advert) you see a table of all active variants:

Column	Meaning
Použít (use)	ticked variants are made for this usage
Varianta, Rozměr a režim (variant, size and mode)	which one it is and what it does (incl. watermark)
Alias (složka) (alias, folder)	the name of the folder the resized copy is stored in; without an alias the folder is named after the variant
Pořadí (order)	the order in which the variants are processed

Unticked variants are collapsed under Zobrazit další varianty (show more variants).

Rules for aliases:

An alias may contain only lowercase letters, digits and a hyphen (at most 32 characters).
An alias is unique within one usage; likewise the same folder must not be created twice.
The alias original is reserved for the original.
Every usage must have its required aliases (usually big — detail — and thumb — thumbnail; the overview is below). Without them nothing is saved and the system tells you which alias is missing.
An inactive variant cannot carry an alias.

What variants without an alias are for. If you leave the alias empty for a variant in a usage, the resized copy is still made and stored in a folder named after the variant — the site just does not use it as the "detail" or the "thumbnail". It serves as another width of the same image. Where a template displays the image responsively, it offers the browser all these widths and the browser downloads the most suitable one for the display (window size and screen density) — a smaller file for a phone, a larger one for a big monitor. If you want images to look sharper on large displays (or to save data on small ones), add several variants with different widths to the usage and leave their aliases empty. The extra widths reach old images only through regeneration, which is optional.

Required aliases#

Site templates ask for some folders by name, so a usage cannot leave them out. Most usages need big and thumb; the images of the System module have their own set:

Usage	Required aliases
Identita webu — favicona (site identity — favicon)	`icon32`, `icon180`, `icon512`
Identita webu — sdílecí obrázek (sharing image)	`big`, `thumb`
Identita webu — logo	`thumb`
Provozovatel — fotka (operator photo)	`avatar`, `thumb`
Knihovna obrázků (image library)	`thumb`
all other usages (Blog, E-shop, Classifieds…)	`big`, `thumb`

When a required alias is missing, the form is not saved and says Chybí varianta s aliasem „…“ — toto použití ji potřebuje (a variant with that alias is missing — this usage needs it); nothing changes. Likewise a variant that carries such an alias cannot be turned off or removed.

Previews in the administration (in lists, in the edit form of an article, a product and so on) use the resized copy with the alias thumb, so they load fast and do not download the large original files. That is why the thumb alias is required for every usage.

Ukládat originál (keep the original) — ticked: besides the resized copies the original file is stored too, in the original folder. Without the original a larger variant cannot be made later. Originals that are already stored can be deleted after you turn this off, see Delete stored originals. For videos the original is always kept, because it is the video itself.

The Uložit obrázky (save images) button saves the usages of that module at once; the message confirms Image settings saved. They apply to newly uploaded images.

Changes apply right away only to NEWLY uploaded images

Files already stored stay as they are — a new variant, a new alias or a switched-off original does not show on old images by itself. Older images work anyway: templates simply offer what an image has. If you wish, the missing resized copies can be added in the Stored images table on the Použití (usages) tab, see Older images: regeneration.

Images of the System module#

The Systém group on the Použití tab controls the variants of images that belong to no content module — the site's own images and the image library in the administration:

Usage	Where the image is uploaded	Default variants (alias: size)
Identita webu — favicona	Site identity, site icon	`icon32`: 32 × 32, `icon180`: 180 × 180, `icon512`: 512 × 512 (all cropped)
Identita webu — sdílecí obrázek	Site identity, sharing image	`big`: 1200 × 630 (crop), `thumb`: 400 × 210 (crop)
Identita webu — logo	Site identity, the other images (logos)	`thumb`: 400 × 200 (proportional)
Provozovatel — fotka	Operator, photo or logo	`avatar`: 240 × 240 (crop), `thumb`: 400 × 400 (proportional)
Knihovna obrázků	Images in the administration	`big`: 1200 × 900, `thumb`: 400 × 300 (proportional)

All five keep the original by default (Ukládat originál). The defaults match what the system made before this setting existed, so nothing changes unless you change it. The required aliases of these usages are in the table above — the favicon needs all three icons because the site template asks for each of them by name.

Here too, a change affects newly uploaded images

If you want, say, a larger sharing image, edit (or add) a variant, assign it to the usage Identita webu — sdílecí obrázek, save, and upload the sharing image again. Images already uploaded can be topped up by regeneration.

Older images: regeneration#

Images that are already on the site have only the resized copies that were made when they were uploaded. If you later add a variant or assign another width, old images lack it. That is fine: older images do not have to have every variant that new ones get — templates simply offer what an image has, so they work without regeneration too. Regeneration is optional: if you want older images to get the new copies as well (e.g. sharper ones for large displays), do it on the usages tab: above the variant assignment there is a Stored images table with one row per usage.

Procedure, if you want to regenerate: add a variant → assign it to a usage → click Regenerate at that usage.

The table shows three numbers for every usage — counts of images (one image can be in more than one column):

Column	Meaning
Images	how many stored images the usage has
Missing current variants	today's setting of the usage has a folder the image does not know, and it can be rendered. This is not an error — older images work without it, templates offer only what an image has. If you want it, Regenerate adds it
Could not be generated	the image record lists the folder but the file is missing on disk, or an earlier regeneration attempt failed. This is an error: Regenerate renders the file again if there is a source
Cannot be regenerated	the original is missing and the target variant is larger than the largest stored reduction without a watermark — nothing is enlarged (see below)
Actions	buttons depending on what makes sense for the usage (see below)

An image that lacks only a record of a file that exists on disk (e.g. original/) is not counted anywhere — it needs nothing.

The Actions cell offers only what makes sense for the usage: Regenerate (with the Also regenerate existing option), Try again only when Could not be generated is not zero, information about originals, and Delete variants outside the current setting only where such files exist.

Regenerate#

The Regenerate button processes one batch of 25 images of that usage and handles both the first and the second state (it renders a folder the image lacks as well as a file the record lists but is missing). A message follows: "Regeneration: … images processed (… files rendered, … overwritten), … failed, … cannot be regenerated, … remaining." While remaining is not zero, click again — repeat until it reaches zero. The same work is done by a scheduled job on the server (arranged by the server administrator).

What the copies are made from. Preferably from the stored original. When no original is stored, only smaller variants are made, from the largest resized copy the image has — nothing is ever enlarged, because an enlarged image would look blurry. Variants larger than the largest existing copy are skipped for such an image and counted under Cannot be regenerated.
What is skipped. Video and SVG are left alone. An image whose best available source carries a watermark is skipped too, so that the watermark is not applied twice or inherited by a variant that should not have it.
Existing files are not overwritten without an explicit instruction. Only copies missing on disk are added; even if you changed the size of a variant in the meantime, finished files stay as they are (you can overwrite them with Also regenerate existing, see below).
Failing images. An image that cannot be processed (e.g. a damaged file) is no longer tried after three attempts and is counted under Could not be generated. The Try again button resets the attempts of the usage and starts the next batch right away. A successful processing resets the attempt counter.
One at a time. Only one regeneration can run at a time. When the scheduled job or another administrator is running it, the system says so; try again in a moment.

Also regenerate existing#

Next to the Regenerate button there is the Also regenerate existing checkbox. When ticked, it also overwrites variant files whose actual dimensions do not match today's setting — for example when you changed the size of a variant and old images still have the original size. Rules:

Only files whose dimensions differ from what would be made from the original today are overwritten. Files with the right size stay untouched. (Dimensions are compared; a change of the watermark is not detected this way.)
Only for images with a stored original. Without an original an existing file is never overwritten.
The file is replaced atomically: the new version is first made into a temporary file and only then replaces the old one, so no broken file is left behind on an error.
The image record (variants and the dimensions) is updated. The scheduled job never overwrites existing files; regenerating is only this action for a single usage.

Regenerating over existing files cannot be undone

The overwritten file is gone. If content from the editor links to it with a fixed size, the look of the page may change too. Try one usage with few images first.

Delete variants outside the current setting#

When you remove a variant from a usage (or replace it with another), older images keep its files — they take space although nothing uses them. The Delete variants outside the current setting button deletes them. The Actions cell shows "outside the setting: count files (size)" and the button is offered only where such files exist. A confirmation appears before deleting:

Files to be deleted: count (size) — variants that images have but today's setting of the usage no longer knows. big, thumb and the original are never deleted. Irreversible: links to these files (for example in editor texts) will stop working.

Rules:

Only a folder that the image has but today's setting of the usage does not is deleted. Never big, thumb or the original (both the folder name and the alias decide).
Only for images with a stored original (a deleted copy could be made again) and only raster images — video and SVG are not deleted.
The record of the variant and its dimensions are removed from the image, the file is deleted and the empty folder too.
Nothing is deleted automatically after regeneration — links to the files may be in editor texts.
Message after deleting: "Variants deleted: X, freed Y, Z failed, W images remaining." (one click handles at most 500 images; delete the rest with another click).

The action is irreversible and has its own permission, which only administrators have.

Delete stored originals#

The original takes the most space on disk. When you turn off Ukládat originál (keep the original) for a usage, new images are stored without it, but old ones keep theirs. You can free that space with the Delete originals button, which is offered for a usage only after keeping the original is turned off. While keeping is on, the Actions cell says only "kept" and there is no button.

The button appears only where some stored originals exist (the cell shows their number and size). Before deleting you see a confirmation:

Stored originals will be deleted: count (size). Irreversible: without the original a larger variant can no longer be regenerated. Images keep rendering from the stored variants.

After you confirm Delete originals, a message reports how many originals are gone, how much space was freed and how many remain (one click deletes at most 500 files; then click again).

Deleting originals cannot be undone

Without the original, a larger variant than the image already has can no longer be made. Regenerate first all variants you want, and only then delete the originals. Images on the site keep rendering from the stored resized copies; video and SVG are not deleted.

Good to know#

When an image is uploaded (classifieds and company catalogue), the file size cap also applies, see Classifieds settings.
The default set of variants is already configured on the site; you need this page only when you want other sizes or another resized copy.
On uploading images in general see Files and images.
The technical description for developers: Image variants in code.

Cookie settings