A set of Joomla 5 extensions for automatic image processing (resizing, format conversion, compression) and photo gallery management.

Package	Version	Joomla	PHP
pkg_semapix	1.2.0	5.x	8.1+ (Imagick or GD)

---

---

1. Requirements

• Joomla: 5.x
• PHP: 8.1 or newer
• PHP extension: Imagick (recommended) or GD
• MySQL: 5.7+ / MariaDB 10.3+
• Disk space: sufficient for processed image variants (each original is processed into 2+ variants)

Recommendation: Imagick provides significantly better quality and processing speed compared to GD. If possible, install the Imagick extension on your server.

---

2. Installation

Obtaining the Installation Package

Download the file pkg_semapix.zip from SemaHub (semakin.cz).

Installation Steps

1. Log in to the Joomla administration panel.
2. Navigate to System > Install > Extensions.
3. Upload the pkg_semapix.zip file.
4. Joomla installs all 5 parts at once in this order:
   • Library: lib_semapix (image processing)
   • Plugin: plg_system_semapix (form field + widget)
   • Module (admin): mod_semapix (quick upload on the dashboard)
   • Component: com_semapixgallery (photo gallery management)
   • Module (site): mod_semapixgallery (gallery display in template positions)
5. The plugin is enabled automatically. The admin module is published to the cpanel position.

Upgrade: Same procedure as installation. Joomla uses method="upgrade" and preserves existing data and settings.

---

3. Package Contents

Extension	Type	Description
lib_semapix	Library	Core – image processing (resizing, format conversion, compression). Adapters for Imagick and GD.
plg_system_semapix	System plugin	Provides an upload widget (type="semapix") for use in any component. Preset and variant definitions.
mod_semapix	Admin module	Drag-and-drop upload directly on the administration dashboard. Quick processing without opening a gallery.
com_semapixgallery	Component	Full photo gallery management – creating, editing, uploading, publishing. Frontend with grid and lightbox.
mod_semapixgallery	Site module	Display a selected gallery in any template position (sidebar, footer, etc.).

---

4. Plugin Configuration (Presets)

Presets define how images are processed – what geometry, format, and compression they receive.

Opening Settings

1. System > Manage > Plugins
2. Search for semapix or Semapix.
3. Click the plugin name.

Default Presets

After installation, a preset gallery is available with variants:

Variant	Geometry	Dimensions	Format	Description
thumb	cover	300×300	webp	Thumbnail for grid preview
large	fit	1200×900	webp	Large version for lightbox

Variant Parameters

Parameter	Description
Variant name	Variant identifier (e.g. thumb, large).
Geometry	scale = resize, fit = fit within dimensions, cover = fill dimensions (with cropping), pad = add background padding.
Width / Height	Target dimensions in pixels.
Format	jpg, png, webp, or auto (preserve original).
Quality	1–100. Default 82. Higher = better quality, larger file.
Max. size (kB)	Optional. Uses binary search to find the best quality for the target file size.
Gravity	For cover and pad geometry. Determines which part of the image is preserved (center, north, south…).
Background	For pad geometry. Fill color for edges (hex, e.g. #ffffff).

Tip: Presets are configured by the site administrator. Regular users (editors) do not need to change them – they are applied automatically when uploading images to a gallery.

---

5. Admin Module – Quick Upload

The admin module appears on the administration dashboard as a “Semapix” panel after installation.

Usage

1. On the dashboard, find the Semapix panel with preset buttons.
2. Click a preset button (e.g. “gallery”).
3. Select images from your computer.
4. Images are immediately processed according to the selected preset.
5. Results are saved to the images/semapix/ folder.

Note: The admin module is intended for quick one-off image processing without creating a gallery. For proper photo galleries, use the component (chapter 6).

---

6. Photo Gallery – Managing Galleries

Access gallery management through the main Joomla administration menu:

1. Log in to your site’s administration panel (/administrator).
2. In the left menu, click “Semapix Galerie” (or “Components > Semapix Galerie”).
3. The list of all galleries is displayed with image counts and publishing status.

If you don’t see the Semapix Galerie item in the menu, the component is not installed. Contact your site administrator.

Gallery List

The gallery list shows a table with these columns:

• Checkbox – for bulk actions (publish, unpublish, trash)
• Status – green icon = published, red = unpublished
• Title – click to open the gallery editor
• Images – number of uploaded images
• Ordering – number determining gallery sort order

Creating a New Gallery

1. In the gallery list, click the “New” button in the top toolbar.
2. The gallery edit form opens.

Field	Description
Title	Required. Gallery name displayed on the website and in administration.
Alias	Optional. URL-friendly identifier. If left empty, it is generated automatically from the title.
Description	Optional text editor. Gallery description displayed above images on the website.
Images	Semapix upload widget – see chapter 7.
Status	Published / Unpublished / Trashed.
Category	Optional category for organizing galleries.
Ordering	Number determining the order in the gallery list.

---

7. Uploading Images

In the gallery editor, you’ll find the “Images” section with the Semapix upload widget. It consists of a file selection button and a list of uploaded images.

Upload Procedure

1. Click the “Select files” button.
2. In the dialog, select one or more images (JPG, PNG, WebP…). You can select multiple files at once using Ctrl/Cmd + click.
3. Images are automatically uploaded and processed. For each image, a thumbnail variant (thumb, 300×300 px) and a large version (large, 1200×900 px) are created.
4. After processing, cards with preview thumbnails appear below the button.
5. To add more images, click “Select files” again – new images are added to the existing ones.

Tip: Images are processed automatically – size, format, and compression are adjusted. You don’t need to edit photos beforehand. The recommended original size is at least 1200 px on the longer side.

Note: There is no file count limit. For large galleries (50+ photos), we recommend uploading in batches of about 10–20 images to avoid exceeding the server’s time limit.

---

8. Managing Images in a Gallery

Reordering

Each image has a drag handle icon on the left. Grab the icon with your mouse and drag the image to the desired position in the list. The order is saved when the gallery is saved.

Removing an Image

Each image has a “Remove” button on the right. Clicking it removes the image from the gallery list. The physical files on the server remain intact – removing from the gallery only disconnects the image from that gallery.

Important: Don’t forget to click “Save” in the top toolbar after making changes. Without saving, reordering and removal changes won’t take effect.

---

9. Gallery Parameters

Below the images, you’ll find the “Gallery Parameters” section where you can customize how the gallery is displayed on the website.

Parameter	Description
Columns	Number of columns in the preview grid (2–6). Default is 4. On mobile devices, the column count is automatically reduced.
Thumbnail variant	Variant name for grid thumbnails. Default: “thumb”. Usually no need to change this.
Large image variant	Variant name for lightbox. Default: “large”. Usually no need to change this.

Tip: If you’re unsure, keep the default values. Columns is the most important parameter – it determines how many images appear in one row on desktop.

---

10. Saving and Publishing

The gallery edit toolbar contains several buttons:

Button	Action
Save	Saves the gallery and stays in the editor.
Save & Close	Saves the gallery and returns to the gallery list.
Save & New	Saves the gallery and opens a form for a new record.
Close	Closes the editor without saving (changes are lost!).

Publishing status can be set either directly in the gallery editor (“Status” field in the right column) or in the gallery list by clicking the status icon:

• Green icon = Published – gallery is visible on the website.
• Red icon = Unpublished – gallery is not visible to visitors.

---

11. Menu Items

For a gallery to appear on the website, a corresponding menu item must exist. Two types are available:

Type A: “Single Gallery”

Displays one specific gallery with images.

1. Navigate to Menu > select the target menu > click “New Item”.
2. Menu item type: select “Semapix Gallery > Single Gallery”.
3. In the parameters, select a gallery from the dropdown list.
4. Set the menu item title and save.

Type B: “Gallery List”

Displays an overview of all published galleries as a tile grid (each gallery as a card with a preview). Clicking a gallery opens its detail view.

1. Navigate to Menu > select the target menu > click “New Item”.
2. Menu item type: select “Semapix Gallery > Gallery List”.
3. Optionally select a category for filtering.
4. Set the title and save.

Note: For both types, you can set the number of columns and image variants in the menu item parameters. These settings override the gallery’s own parameters.

Recommendation: After creating a menu item, we recommend clearing the Joomla cache: System > Clear Cache.

---

12. Frontend Display

Image Grid

The gallery is displayed on the website as a grid of thumbnail images. The number of columns adapts to the screen size:

• Desktop: number per settings (default 4 columns)
• Tablet: 2–3 columns
• Mobile: 1 column

Lightbox

Clicking an image opens a lightbox – a large version of the photo displayed fullscreen with a dark background. Controls:

• Left / right arrow or clicking the edges – previous / next photo
• Esc key or clicking the close button – close the lightbox
• Counter in the bottom-left corner shows the position (e.g. 3 / 24)

Pagination

If a gallery has more images than fit on one page (default 5 rows), pagination buttons appear below the grid. Even with pagination, the lightbox allows browsing all photos in the gallery.

---

13. Gallery Module (mod_semapixgallery)

The module allows displaying a selected gallery in any template position (sidebar, footer, content area, etc.).

Module Settings

1. Navigate to Content > Site Modules.
2. Find the “Semapix Gallery” module (created automatically during installation).
3. Or create a new module of type “Semapix Gallery”.

Parameter	Description
Gallery	Select a gallery from the dropdown list.
Columns	Number of columns in the grid (2–6).
Thumbnail variant	Variant name for thumbnails. Default: “thumb”.
Large image variant	Variant name for lightbox. Default: “large”.
Lightbox	Enable/disable lightbox on image click.
Pagination	Enable/disable pagination for larger image sets.
Max. images	Limit the maximum number of displayed images (0 = all).
Link	Optional URL link – displays a “View gallery” button below the grid.
Position	Template position (sidebar, footer, content, etc.).

Important: The module uses CSS and JavaScript from media/com_semapixgallery/. The com_semapixgallery component must be installed.

---

14. Managing Existing Galleries

Editing

In the gallery list, click a gallery’s title – the editor opens. You can change the title, description, add/remove images, change parameters, and publishing status.

Bulk Actions

In the gallery list, you can select multiple records (checkboxes) and use the toolbar buttons:

• Publish – make selected galleries visible on the website
• Unpublish – hide selected galleries
• Trash – move selected galleries to the trash

Emptying the Trash

Trashed galleries are shown when setting the “Status” filter to “Trashed”. Select the records and click “Empty Trash” for permanent deletion.

Search and Filtering

Above the table is a search field for finding galleries by title. Filters allow displaying only galleries with a specific status or category.

---

15. Uninstallation

Procedure

1. System > Manage > Extensions
2. Search for Semapix or pkg_semapix.
3. Select the package and click Uninstall.

What Gets Deleted

• All 5 extensions (library, plugin, admin module, component, site module)
• Table #__semapixgallery (gallery data)

What Is PRESERVED

• Processed images in the images/semapix/ folder

If you want to remove the images as well, manually delete the images/semapix/ folder via FTP or File Manager.

---

16. Troubleshooting

Gallery Does Not Appear on the Website

• Verify the gallery has the status “Published”.
• Verify a menu item pointing to the gallery exists (see chapter 11).
• Clear the cache: System > Clear Cache.

Images Don’t Show After Upload

• Make sure you clicked “Save” after uploading.
• Check that the upload completed successfully (preview cards appeared).
• For larger batches, try uploading a smaller batch.

Images Have Poor Quality

Upload images at the highest possible resolution. Processing creates optimized versions – a smaller original means a worse result.

Upload Error

• Check that the files are images (JPG, PNG, WebP, GIF).
• Check the file size – the server may have a limit (typically 2–32 MB per file).
• Check that Imagick or GD is installed on the server.
• If the error persists, contact your site administrator.

Changing the Column Count

The number of columns can be changed in two places:

• In the gallery parameters (“Gallery Parameters” section in the editor) – applies to that gallery.
• In the menu item parameters – overrides the gallery settings for that menu link.

Plugin Semapix Not Showing in the Plugin List

• Verify the pkg_semapix package is installed (not individual ZIP files).
• Try Extensions > Manage > Discover to detect the extensions.

Admin Module Not Showing on the Dashboard

• Verify the module is published: Content > Administrator Modules > search for “Semapix”.
• Check the module position – it should be cpanel.

---

Image Output Folder

All processed images are saved to:

images/semapix/{preset}/{variant}/

For example:

• images/semapix/gallery/thumb/ – thumbnails
• images/semapix/gallery/large/ – large versions

Folders are created automatically. Original uploaded files are not stored – only processed variants are saved.

---

Launch Checklist

• Package installed (pkg_semapix.zip)
• Semapix plugin is enabled with the lowest possible ordering (System > Plugins)
• Presets configured as needed (default gallery is sufficient for basic use)
• At least one gallery created and published
• Menu item pointing to the gallery created
• Test image upload completed and images display on the frontend
• Joomla cache cleared