Configure JEM image limits, thumbnails, aspect-ratio profiles, publication requirements and storage folders for events, venues and categories.
Available in JEM 5.1.0 Beta 4. The standalone Images tab is new in JEM 5.1.0. In JEM 5.0.1 and JEM 5.0.2 Beta 1, the classic image options remain under Basic Settings.
These settings define global image policies. They control newly assigned or uploaded images. Existing images are normally preserved unless an administrator replaces, repairs or relocates them by saving the corresponding item.
Navigation and Access
In the Joomla administrator, select Components → JEM → Settings → Images.
Opening or saving JEM Settings requires the applicable Joomla/JEM core.options permission. Saving validates the complete Settings form, including fields on tabs that are not currently visible.
Images at a Glance
Global Limits
Allowed formats, file size and image dimensions.
Image Profiles
Independent rules for four different image roles.
Storage
Optional subfolders for events, venues and categories.
Legacy Repair
Detect and resize oversized stored event images.
Recommended Configuration Flow
1 Define safe limits Set the accepted file types, size and image dimensions.
2 Configure profiles Choose the default resolution and ratio for each image role.
3 Choose flexibility Decide whether editors may override the resolution or ratio.
4 Organise storage Enable subfolders only when they improve media management.
5 Test the workflow Upload, edit, publish and display every supported image type.
General Image Options
| Field | Initial value | Purpose and behaviour |
|---|
Allowed Image Files
image_filetypes |
jpg,gif,png,webp |
Comma-separated file extensions accepted by JEM image uploads. Only enable formats supported by the PHP image-processing library and the browsers used by the site. |
Max. Image Filesize (KB)
sizelimit |
400 KB |
Maximum file size accepted by JEM. PHP, the web server or a reverse proxy may enforce a lower upload limit. |
Minimum Original Dimension (px)
image_min_dimension |
64 px |
Both the width and height of a newly assigned image must meet this minimum. The value cannot be lower than 64 pixels or higher than the configured maximum. |
Max. Original Dimension (px)
image_max_dimension |
2560 px |
Maximum permitted width or height for newly assigned images. The configurable range is 320 to 8192 pixels. JEM can reduce an uploaded image according to its profile. |
Max. Width of Thumbnails
imagewidth |
200 px |
Maximum width of generated thumbnails and category pictures. An empty value is normalised to 100 pixels when Settings is saved. |
Max. Height of Thumbnails
imagehight |
200 px |
Maximum height of generated thumbnails and category pictures. An empty value is normalised to 100 pixels when Settings is saved. |
Enable Pop Up Thumbnail
gddisabled |
Yes |
Enables thumbnail creation and an enlargement action. This option is available when GD version 2 or later is detected on the server. |
Lightbox Effect
lightbox |
Yes |
When thumbnail enlargement is enabled, opens the original image in JEM's Lightbox overlay. When disabled, compatible layouts use a separate browser popup. |
Flyer
flyer |
No |
Displays the original-resolution image instead of the standard thumbnail workflow. Large originals can increase page weight and mobile loading time. |
Initial values are those applied by JEM 5.1.0. Upgrades preserve most existing settings, although a previous standard 200 KB image limit is migrated to the new 400 KB default.
The global maximum is a processing boundary, not a display size. The browser can display an image at a smaller CSS size, but the original file still consumes storage, memory and bandwidth. Upload images prepared for their intended role.
Thumbnail Display Combinations
| Flyer | Pop Up Thumbnail | Lightbox | Standard result |
|---|
| No |
No |
Not applicable |
A static generated thumbnail is displayed. |
| No |
Yes |
No |
Selecting the thumbnail opens the original image in a separate browser popup. |
| No |
Yes |
Yes |
Selecting the thumbnail opens the original image in the Lightbox overlay. |
| Yes |
Any |
Any |
The original image is used directly by the standard flyer output. |
Changing the thumbnail width or height does not automatically rebuild every previously generated thumbnail. Existing thumbnails may need to be regenerated or the corresponding item may need to be processed again.
Image Profiles
JEM defines four independent image profiles. This allows a landscape event-list image, a larger detail image, a venue image and a square category image to use different policies.
Event intro/list image
Primary event image used in lists, cards and as the Joomla associated article intro image.
- Default resolution: 1200 px
- Default ratio: 16:9
- Automatic adjustment: None
- Required to publish: No
Event full/detail image
Optional larger image used on the event-detail page and as the Joomla associated article full image.
- Default resolution: 1920 px
- Default ratio: 16:9
- Automatic adjustment: None
- Required to publish: No
Venue image
Main image assigned to a venue and displayed by compatible venue and event layouts.
- Default resolution: 1280 px
- Default ratio: 4:3
- Automatic adjustment: None
- Required to publish: No
Category image
Image assigned to a JEM category and used by compatible category views and layouts.
- Default resolution: 800 px
- Default ratio: 1:1
- Automatic adjustment: None
- Required to publish: No
Options Available in Every Profile
| Field | Initial value | Purpose and behaviour |
|---|
| Image required to publish |
No |
When enabled, an unpublished item can still be saved, but it cannot be published until the referenced image file exists. |
| Default upload resolution (px) |
Depends on profile |
Initial maximum side used when processing a new image. It must remain within the global dimension boundaries. |
| Resolution mandatory |
No |
No allows an editor to choose another valid resolution for an individual upload. Yes fixes the upload to the profile's configured resolution. |
| Automatic adjustment |
No adjustment |
Controls whether JEM preserves the original ratio, adds padding or centre-crops the image to the selected ratio. |
| Aspect ratio |
Depends on profile |
Default horizontal or vertical ratio for this image role. Ratios are not inverted automatically. |
| Aspect ratio mandatory |
No |
No allows an editor to select another supported ratio for one upload. Yes enforces the configured profile ratio. |
| Custom ratio |
Profile default |
Displayed when Custom is selected. Enter two positive whole numbers separated by a colon, for example 35:3. JEM reduces equivalent values such as 1920:1080 to 16:9. |
Automatic Adjustment Modes
| Mode | Result | Recommended use |
|---|
| No adjustment |
Preserves the image's natural aspect ratio. Images exceeding the selected maximum are proportionally reduced without unnecessary upscaling. |
Photography, legacy compatibility and layouts that accept mixed proportions. |
| Fit with black bars |
Fits the complete image inside the selected ratio and adds black padding where necessary. |
Logos, posters or artwork that must remain completely visible. |
| Centre crop |
Crops the image to the exact selected ratio. The image editor allows the visible area to be positioned and zoomed. |
Consistent cards, grids, hero areas and other aligned image collections. |
Available Aspect Ratios
| Ratio | Orientation | Typical use |
|---|
1:1 |
Square |
Category icons, logos and square cards. |
4:3 |
Landscape |
Venue and documentary photography. |
3:4 |
Portrait |
Vertical venue photography. |
3:2 |
Landscape |
Standard photography. |
2:3 |
Portrait |
Posters and programme covers. |
8:5 |
Landscape |
Wide content cards. |
5:8 |
Portrait |
Vertical promotional artwork. |
16:9 |
Landscape |
Event cards, banners and detail headers. |
9:16 |
Portrait |
Mobile-first posters and stories. |
21:9 |
Panoramic |
Wide headers and hero images. |
9:21 |
Vertical panoramic |
Narrow vertical promotional layouts. |
| Custom |
User-defined |
Special designs such as 35:3. |
Per-upload control: when Resolution mandatory or Aspect ratio mandatory is disabled, the editor can choose another permitted value while uploading an image. This changes only that upload and does not modify the global profile.
When No adjustment is configured, the default upload ratio is Original. If an editor explicitly selects another ratio for an individual upload, JEM processes that selection as a crop unless another adjustment mode is configured.
Publication Requirements
Each profile can independently require its image before the corresponding item is published.
| Item | Profile checked | Behaviour when the image is missing |
|---|
| Event |
Event intro/list image |
The event can be saved as unpublished, but it cannot be published without the intro image. |
| Event |
Event full/detail image |
The event can be saved as unpublished, but publication requires a separate valid full image. A display fallback to the intro image does not satisfy this requirement. |
| Venue |
Venue image |
The venue can be saved as unpublished, but it cannot be published without its main image. |
| Category |
Category image |
The category can be saved as unpublished, but it cannot be published without its image. |
JEM verifies that the referenced file exists. A filename stored in the database is not sufficient when the physical image has been deleted or moved outside JEM.
Enable requirements carefully on an existing site. Items already missing the required image may be prevented from being published again until their image is restored.
Image Storage
JEM can store newly uploaded images in structured subfolders instead of keeping every image in a single flat directory.
Event images
images/jem/events
The intro and full event images share the event's configured relative folder.
Venue images
images/jem/venues
The setting controls the main venue image. Venue Profile, Space, Layout and Area media retain their stable capacity-storage paths.
Category images
images/jem/categories
Category folders can follow the category hierarchy, type or a custom pattern.
Generated thumbnails use the same relative structure below each object's small directory.
Event Image Folder Structures
| Preset | Pattern | Example |
|---|
| Root events image folder |
No subfolder |
images/jem/events |
| Year |
{year} |
images/jem/events/2026 |
| Year / category |
{year}/{category_alias} |
images/jem/events/2026/training |
| Year / category / venue |
{year}/{category_alias}/{venue_alias} |
images/jem/events/2026/training/main-campus |
| Category / venue |
{category_alias}/{venue_alias} |
images/jem/events/training/main-campus |
| Venue / year |
{venue_alias}/{year} |
images/jem/events/main-campus/2026 |
| Custom pattern |
Administrator-defined |
{year}/{month}/{type_alias} |
Venue Image Folder Structures
| Preset | Pattern | Example |
|---|
| Root venues image folder |
No subfolder |
images/jem/venues |
| Venue ID / venue |
{venue_id}/venue |
images/jem/venues/42/venue |
| City / venue |
{city}/{venue_alias} |
images/jem/venues/madrid/main-campus |
| Country / city / venue |
{country}/{city}/{venue_alias} |
images/jem/venues/es/madrid/main-campus |
| Type / venue |
{type_alias}/{venue_alias} |
images/jem/venues/university/main-campus |
| Custom pattern |
Administrator-defined |
{year}/{city}/{venue_id} |
Category Image Folder Structures
| Preset | Pattern | Example |
|---|
| Root categories image folder |
No subfolder |
images/jem/categories |
| Category |
{category_alias} |
images/jem/categories/training |
| Parent category / category |
{parent_category_alias}/{category_alias} |
images/jem/categories/education/training |
| Type / category |
{type_alias}/{category_alias} |
images/jem/categories/course/training |
| Custom pattern |
Administrator-defined |
{year}/{type_alias}/{category_alias} |
Custom Pattern Tokens
| Object | Available tokens |
|---|
| Event |
{year}, {month}, {month_name}, {quarter}, {week}, {event_id}, {event_alias}, {category_alias}, {venue_alias}, {city}, {region}, {country}, {type_alias}, {import_source} and {import_profile} |
| Venue |
{year}, {venue_id}, {venue_alias}, {city}, {region}, {country} and {type_alias} |
| Category |
{year}, {category_id}, {category_alias}, {parent_category_alias} and {type_alias} |
- Custom patterns can contain no more than eight folder levels.
- Folder names are converted to safe URL-compatible values.
- Unknown or unavailable token values are removed from the resolved path.
- All resolved paths remain below the applicable JEM image root.
- For events, the first available category is used for
{category_alias}.
Enabling or changing a folder structure is not an immediate bulk migration. An existing referenced image keeps its current path until the related event, venue or category is saved. JEM then relocates the applicable image and thumbnail when required.
Repairing Oversized Legacy Event Images
Images imported from older JEM versions or uploaded directly through another media tool may exceed the current JEM maximum. When editing an affected event in the backend, JEM analyses both its intro and full images.
- Open Components → JEM → Events.
- Edit the affected event.
- Open its Image section.
- Read the warning showing the stored image dimensions and the current maximum.
- Select Resize to [maximum] px.
- Confirm that the stored original may be replaced.
- Verify the rebuilt image and thumbnail on the frontend.
The repair replaces the stored original. If several items reference the same physical file, they will all use the resized version. Create a backup before repairing important source artwork.
The automatic repair is offered only when JEM can safely process the file as a static image and the required GD functionality is available. Otherwise, prepare a smaller image externally and replace the stored file manually.
Practical Configuration Examples
- Global dimensions: 64 to 2560 px.
- Event intro image: 1200 px, 16:9, Centre crop.
- Resolution mandatory: No.
- Aspect ratio mandatory: Yes.
- Image required to publish: Yes.
This produces aligned event-list cards while allowing editors to reduce the upload resolution when appropriate.
- Event full image: 1920 px.
- Aspect ratio: 2:3.
- Automatic adjustment: Fit with black bars.
- Resolution mandatory: No.
- Aspect ratio mandatory: Yes.
The complete poster remains visible inside a consistent vertical canvas.
- Enable event image subfolders.
- Select Year / category / venue.
- Enable Venue ID / venue for venue images.
- Select Parent category / category for category images.
This keeps large media collections organised without allowing paths outside the JEM image directories.
- Require the Event intro, Event full, Venue and Category images.
- Make profile resolutions and aspect ratios mandatory.
- Use crop for cards and detail headers.
- Train editors to save incomplete content as unpublished.
This provides highly consistent public output, but it also requires a complete image workflow for every new item.
- Automatic adjustment: No adjustment.
- Publication requirements: No.
- Resolution and ratio mandatory: No.
- Image subfolders: Disabled.
This preserves the traditional flexible workflow while still enforcing safe global upload limits.
Troubleshooting
| Problem | Likely cause | Recommended action |
|---|
| Settings cannot be saved |
The minimum exceeds the maximum, a default resolution is outside its valid range, a custom ratio is invalid or a folder pattern is too deep. |
Review the validation message and correct the affected profile or pattern. |
| A new image is rejected |
Its extension, file size, width or height is outside the global limits. |
Prepare the image within the configured limits or review the site's upload policy. |
| The configured ratio cannot be saved |
The ratio cannot produce an image whose width and height both fit between the configured minimum and maximum. |
Choose a less extreme ratio or adjust the dimension limits. |
| An animated image cannot be processed |
The image requires resizing, orientation correction, padding or cropping. |
Upload a prepared static image or use No adjustment when the original already meets the limits. |
| An item cannot be published |
A profile is configured as required and its referenced file is missing. |
Add the marked image or save the item as unpublished. |
| The Lightbox option is not available |
Pop Up Thumbnail is disabled or the required GD functionality is unavailable. |
Check the server's PHP GD extension and enable Pop Up Thumbnail. |
| Existing thumbnails retain their old dimensions |
Changing the thumbnail limits does not automatically rebuild previously generated files. |
Regenerate or reprocess the affected thumbnails. |
| Subfolders are not created |
The image root is not writable or the pattern resolves to invalid or unavailable values. |
Check Joomla folder permissions and simplify the configured pattern. |
| An old event image exceeds the maximum |
The file came from an older version or was uploaded outside the current JEM policy. |
Use the backend event image repair button or replace it with a prepared image. |
Version Differences
| Version | Image configuration location | Available image features |
|---|
| JEM 5.0.1 |
Settings → Basic Settings |
Classic file-type, file-size, thumbnail, Lightbox and Flyer options. |
| JEM 5.0.2 Beta 1 |
Settings → Basic Settings |
Classic image configuration and maintenance fixes. |
| JEM 5.1.0 Beta 4 |
Settings → Images |
Global limits, four image profiles, per-upload controls, mandatory publication rules, structured storage and oversized event-image repair. |
Before Saving
- Confirm that every profile default fits inside the global dimension limits.
- Test landscape, portrait and square uploads.
- Verify frontend and backend event editing.
- Verify venue and category image editing.
- Test saving both published and unpublished items.
- Check thumbnails, Lightbox and Flyer output.
- Test the selected storage structure with items that have missing optional tokens.
- Back up important original images before using the repair action.
Related Resources
Beta notice: JEM 5.1.0 Beta 4 is intended for testing before production deployment. Back up the site and test image upload, processing and storage with the server's actual PHP limits and image libraries.
