Isotope Gallery Documentation

1. Requirements

• Joomla 3.6 or newer, php8+.
• The module must be installed in modules/mod_mx_isotopegallery.
• For image resizing, PHP GD support and a writable Joomla cache directory are recommended.
• For YouTube and Vimeo items, the visitor's browser must be able to load the external media.

2. Installation and Publishing

1. In Joomla administrator, open System > Install > Extensions.
2. Upload mod_mx_isotopegallery.zip and complete the installation.
3. Open Extensions > Modules and create or edit an Isotope Gallery module.
4. Choose a template position, set the module to Published, and configure menu assignment.
5. Save the module and open an assigned front-end page.

The package uses files from its assets, core, field, elements, and tmpl directories. Keep these directories when moving or updating the module.

3. Quick Start

1. Choose Articles, Custom Items, or Folder in Source.
2. Configure the fields shown for that source and add at least one usable item or article.
3. Choose Gallery or Isotope in Layout, then select the number of columns.
4. Choose whether the popup gallery is enabled and configure its controls in Gallery Settings.
5. Publish the module in a position rendered by the active template.

4. Source Options

Articles

Articles are loaded from Joomla's com_content component and are limited to published, accessible articles and the active language.

• Select Category chooses the article categories.
• Child Category Articles includes child categories when enabled.
• Category Depth limits how many child levels are included.
• Featured Articles shows all, hides, or displays only featured articles.
• Article Field to Order By supports manager order, featured order, hits, title, ID, alias, and publishing dates.
• Ordering Direction chooses ascending or descending order.
• Count sets the maximum number of articles. A value of 0 means no limit.
• Open Link opens the article in the same window, a new window, or a popup window.

Article text and metadata

• Category Title, Item Title, Description, Date, Author, and Read More can be shown or hidden.
• Title Maxlength and Description Maxlength truncate displayed text. Use 0 to show all text.
• Date Format accepts the listed PHP date formats, such as Y-m-d and l, d F Y.
• Read More Text changes the label used for the article link.

Custom Items

Custom items are entered in the Items(s) subform. Add one row for each gallery item.

To use custom filtering, enable Use filtering, create filter names in the Filter(s) subform, and use the same names in each item's Filter Name.

Folder

Select a directory below the site's images directory with Folder directory. The module scans that directory and its subdirectories.

• Image order supports alphabetical order, most recent first, and random order.
• Supported local media extensions include jpg, jpeg, png, gif, bmp, webp, mp4, webm, ogg, ogv, mov, and m4v.
• Image title displays the filename without its extension. Underscores, hyphens, and numbers are converted into spaces.
• When Use filtering is enabled, the first-level subfolder names become filter buttons.

images/gallery/landscape/sunrise.jpg
images/gallery/portrait/person.jpg

With images/gallery selected, landscape and portrait can be used as folder filters.

5. Filtering

Article filters

For Articles, enable Category filters and/or Tag filters. Filter buttons are generated from categories and tags present in the loaded article results. Enable Show filter labels to display the configured labels, and enable Show All button to display the all-items button with the text from All button text.

Custom item filters

Custom filter names are CSS class names. Keep names simple and use the same spelling in the filter definition and item rows. If an item contains several names, it appears in each matching filter.

Folder filters

Folder filters use the first directory level below the selected folder. Files directly inside the selected folder do not belong to a named folder filter but remain visible through All.

6. Images and Resize

Article image sources

Enable the desired image sources and define their priority in Order to Get. The default order is:

image_intro, image_fulltext, inline_introtext, inline_fulltext

• From Image Intro reads the article intro image.
• From Image Fulltext reads the article full-text image.
• From Inline Introtext finds images inside the intro text.
• From Inline Fulltext finds images inside the full text.

The first available image in the configured order is used. Placeholder Path supplies the fallback image when no article image is available.

Resize settings

Set Resize Mode to a resize option to create cached versions of local images. None leaves the original image unchanged.

• Center resizes while centering the result.
• Fill resizes to fill the requested dimensions and may crop the edges.
• Fit keeps the image inside the requested dimensions.
• Stretch forces the requested width and height and can change the aspect ratio.
• Quality compression accepts values from 1 to 100.
• Output Format can keep the source format or generate GIF, JPEG, PNG, or WEBP.
• Keep Transparency applies to GIF and PNG output.
• Image Width and Image Height define the target dimensions. Values must be greater than zero when resizing is enabled.

Generated files are stored in the Joomla cache resize directory. Make sure PHP can create and write that directory. External images and video media are not processed by the image resize helper.

7. Layout and Appearance

• Layout: Gallery uses the gallery item treatment; Isotope uses the isotope grid treatment.
• Parallax effect: enables parallax images for Isotope layout.
• Columns: selects one to six columns.
• Style: chooses the Light or Dark stylesheet.
• Details: places details on hover or shows them by default.
• Color: sets the accent color for backgrounds, links, and active filters.
• Items space: selects the gap between items.
• Font awesome: loads Font Awesome 4 or 5 only when needed for icon compatibility.
• SEO fixes: enable this when the template needs the site root path added to gallery image thumbnails.
• Load Jquery: enable only when the template does not already provide jQuery.
• Custom CSS: adds CSS declarations to the page. Scope selectors to the module to avoid changing other components.

8. Gallery Settings

These settings configure the LightGallery popup. They have an effect only when Use popup gallery is enabled.

Local folder videos and custom YouTube or Vimeo items use the gallery's video support when the popup is enabled. Browser autoplay policies may require muted playback or user interaction.

9. Advanced Settings

• Module Class Suffix adds a class suffix to the module wrapper for template-specific styling.
• Alternative Layout selects an available module layout override.
• Caching can use the global Joomla setting or disable module caching.
• Cache Time sets the cache lifetime when caching is enabled.

10. Troubleshooting

No items appear

• Confirm the module is published, assigned to the current menu item, and placed in a rendered template position.
• For Articles, check publication state, access level, language, categories, featured settings, and count.
• For Custom Items, confirm that the subform contains items and that image or video URLs are valid.
• For Folder, verify that the selected path exists below images and contains supported files.

Filters are missing

Article filters are built only from the current article result. Custom filters require matching names in both the filter list and item rows. Folder filters require first-level subdirectories.

Images are not resized

Choose a resize mode, enter positive dimensions, confirm PHP GD support, and check that the Joomla cache directory is writable. Resize processing applies to local images, not remote URLs or video.

The popup does not open

Enable Use popup gallery, check for JavaScript errors or library conflicts, and avoid loading a second incompatible jQuery copy. Clear Joomla and browser caches after changing scripts or styles.

Video does not play

Check the media URL, file permissions, MIME type, browser support, and external provider privacy or embedding settings. Autoplay can be blocked by the browser until the visitor interacts with the page.

11. Updating

Back up the module configuration and site files before updating. Install the newer ZIP through Joomla's extension installer. The extension manifest declares an update server, so Joomla may also offer updates when the server is reachable.