Vertex Gallery is a complete gallery solution for Joomla 4, 5, and 6, combining a powerful module and content plugin. Display stunning galleries in module positions or embed them directly in articles using simple shortcodes.

Key Features:

• Module Component: Display galleries in any module position with full backend configuration
• Content Plugin: Embed galleries in articles using {vertexgallery} shortcodes
• Editor Button: Insert shortcodes easily from the Joomla editor toolbar
• Grid and Masonry layouts with responsive column controls
• Advanced modal lightbox with dark/light themes and comprehensive controls
• Folder-based or manual slide management
• Subfolders as category filters (module option)
• Multiple folder paths with custom category labels
• Category filtering system
• Automatic image resizing and WebP conversion
• Extensive customization options (colors, filters, captions, etc.)
• Fully responsive and touch-friendly
• Joomla 4, 5 & 6 compatible

Perfect for portfolios, photo galleries, product showcases, and any image-rich content. Both components share the same powerful gallery engine, ensuring consistent functionality and appearance across your site.

Package Installation

Vertex Gallery is distributed as a package containing the module, content plugin, and editor button. To install:

1. Log in to your Joomla backend
2. Navigate to System > Install > Extensions
3. Drag and drop or browse for pkg_vertexgallery.zip
4. Click Install

After Installation

Components are installed and the content plugin is enabled by default:

• Module: Go to Content > Site Modules and create a new "Vertex Gallery" module instance
• Plugin: Go to System > Plugins and find "Content - Vertex Gallery" to configure default settings
• Editor Button: "Editors Xtd - Vertex Gallery" appears in the editor toolbar when enabled

System Requirements

• Joomla 4.0.0 or higher (4.x, 5.x, 6.x)
• PHP 7.4.0 or higher
• PHP GD extension (for image resizing and WebP conversion)
• Modern web browser (Chrome, Firefox, Safari, Edge)

Verifying Installation

After installation, verify components are installed:

1. Check System > Manage > Extensions — you should see mod_vertexgallery, plg_content_vertexgallery, and plg_editors-xtd_vertexgallery
2. Verify the content plugin is enabled
3. Create a test module or use a shortcode in an article to confirm functionality

Creating a Gallery Module

To create a Vertex Gallery module instance:

1. Go to Content > Site Modules
2. Click New
3. Select Vertex Gallery from the module type list
4. Configure the module settings
5. Assign to a module position
6. Set menu assignment (All pages, Selected pages, etc.)
7. Set Status to Published
8. Click Save

Module Configuration Tabs

• Image Source: Folder-based or manual slides, folder path, subfolder filters
• Layout & Visual: Layout style, columns, gaps, visual themes, show filter
• Modal/Lightbox Settings: Modal configuration, controls, autoplay, captions
• Image Resize Settings: Thumbnail and modal image sizing, WebP conversion
• Gallery Behavior: Randomization, single image preview
• Advanced: Module suffix and extra CSS

Use Subfolders as Filters (recommended for multi-category galleries)

If you organize images like this:

images/gallery/
  Animals/
  Teams/
  Farm Shop/

1. Set Image Source Type to Folder
2. Set Image Folder Path to images/gallery
3. Set Use Subfolders as Filters to Yes
4. Enable Show Gallery Filter in Layout & Visual
5. Save and clear cache

Filter buttons will show: All, Animals, Teams, Farm Shop (from each immediate subfolder name).

Images placed directly in images/gallery keep the parent folder name (Gallery) as their category.

Multiple Folder Paths

You can also list folders explicitly in Image Folder Path:

• Multiple folders: images/gallery/Animals,images/gallery/Teams,images/gallery/Farm Shop
• Custom labels: images/gallery/Animals|Animals,images/gallery/Teams|Teams

Manual Slides with Categories

Set Image Source Type to Slides, add each image, and enter a Category (e.g. Animals, Teams). Filters are built from those category names.

Multiple Instances

You can create multiple gallery module instances. Each gets a unique ID (vg-mod-{module_id}) for CSS targeting.

Where to Insert Shortcodes

Do not put shortcodes in CSS. Shortcodes belong in content areas:

• Articles — paste into the article body (Code/HTML view if needed)
• Custom HTML modules — paste into the module HTML
• Category descriptions, menu item descriptions, or other HTML content areas

Ensure Content - Vertex Gallery is enabled under System > Plugins.

Basic Shortcode Syntax

{vertexgallery folder="images/gallery"}

or

{vertexgallery images="image1.jpg,image2.jpg,image3.jpg"}

Multiple Folders (category filters)

List each category folder. The folder name becomes the filter (or use |Label for a custom name):

{vertexgallery folders="images/gallery/Animals,images/gallery/Teams,images/gallery/Farm Shop"}

{vertexgallery folders="images/gallery/Animals|Animals,images/gallery/Teams|Teams,images/gallery/Farm Shop|Farm Shop"}

Shortcode Attributes

• folder — Single folder path (e.g. "images/gallery")
• folders — Multiple folders, comma-separated; optional path|Label per entry
• images — Comma-separated image paths
• layout — "grid" or "masonry"
• columns — "auto", a number, or "1,2,3" for responsive
• gap — Gap in pixels (default: 16)
• show_filter — "1" or "0"
• enable_modal — "1" or "0"
• modal_theme — "dark" or "light"

More Examples

{vertexgallery folder="images/portfolio"}

{vertexgallery folder="images/gallery" layout="masonry" columns="3" gap="20"}

{vertexgallery folder="images/products" show_filter="1" enable_modal="1" modal_theme="light"}

Module vs Shortcode

If you already use the Vertex Gallery module, you do not need a shortcode. Configure folders and Use Subfolders as Filters in the module settings instead. Use shortcodes when embedding a gallery inside article text or a Custom HTML module.

Folder-Based Images

Automatically load images from one or more folders:

1. In module: Set Image Source Type to "Folder"
2. Enter Image Folder Path (e.g. images/gallery)
3. Optionally enable Use Subfolders as Filters
4. Optionally enable Auto-Generate Titles from Filenames

Supported Formats: JPG, JPEG, PNG, GIF, WebP

How Categories Are Assigned

• Single folder (subfolders off): All images use that folder name as the category (e.g. images/gallery → Gallery). Filters show All + Gallery.
• Use Subfolders as Filters = Yes: Each immediate subfolder becomes its own filter. Nested folders deeper than one level are not scanned.
• Multiple paths: Each listed folder becomes a category; use path|Label for custom filter names.

Manual Slides

1. Set Image Source Type to "Slides"
2. Click Add for each image
3. Configure Image, Title, Description, and Category

Best for curated galleries where you set category names yourself.

Image Paths

• Correct: images/gallery/photo.jpg
• Incorrect: /images/gallery/photo.jpg (leading slash)
• Incorrect: absolute URLs

Best Practices

• Create one subfolder per category under a parent gallery folder
• Enable Use Subfolders as Filters on the parent path for automatic filters
• Use descriptive folder names — they become filter labels
• Keep image file sizes reasonable for performance

Layout Types

Choose between two layout styles:

• Grid: Clean, organized grid layout with uniform columns. Perfect for consistent, structured displays.
• Masonry: Pinterest-style layout that automatically arranges images without gaps. Ideal for images with varying aspect ratios.

Columns Configuration

Set the number of columns in three ways:

• Auto: Automatically calculates optimal column count based on container width
• Single Number: Fixed number of columns (e.g., "3" for 3 columns)
• Responsive Format: "1,2,3" means 1 column on mobile, 2 on tablet, 3 on desktop

Example: "1,2,4" creates a responsive grid that adapts to screen size.

Gap Settings

Control spacing between gallery items:

• Gap: Space between items in pixels (default: 16)
• Larger gaps create more breathing room
• Smaller gaps create tighter, more compact galleries
• Recommended range: 8-32 pixels

Gallery Max Width

Limit the maximum width of the gallery container:

• Leave empty for full-width display
• Enter value in pixels (e.g., "1200") or with unit (e.g., "1200px")
• Gallery will center if max width is smaller than container

Item Aspect Ratio

Set fixed aspect ratio for gallery items (Grid layout only, ignored in Masonry):

• Leave empty for natural aspect ratio
• Format: "width/height" (e.g., "16/9", "4/3", "1/1")
• All items will have the same aspect ratio for uniform grid
• Images are cropped to fit the aspect ratio

Visual Settings

• Corner Style: Rounded or Flat corners
• Show Card Shadow: Enable/disable shadow effect on gallery items
• Accent Color: Color for filter buttons, active states, and UI elements
• Show Gallery Filter: Show or hide category filter buttons

Basic Modal Settings

Configure the lightbox modal for viewing images:

• Enable Modal: Turn modal on/off (default: enabled)
• Modal Theme: Dark or Light theme
• Modal Backdrop Opacity: Background overlay transparency (0.0 to 1.0, default: 0.8)
• Modal Transition: Fade, Crossfade, or Slide transitions between images
• Swipe Threshold: Minimum distance in pixels to trigger swipe on mobile (default: 50)
• Disable Right Click: Prevent right-click context menu to protect images

Modal Controls

Control which buttons and features appear in the modal:

• Play/Pause Button: Control autoplay slideshow
• Speed Slider: Adjust autoplay speed
• Image Count: Display current image number (e.g., "1/10")
• Thumbnails Strip: Show thumbnail navigation at bottom
• Thumbnails Toggle: Button to show/hide thumbnail strip
• Fullscreen Button: Toggle fullscreen mode
• Rotate Controls: Rotate left/right buttons
• Flip Controls: Flip horizontal/vertical buttons
• Zoom Controls: Zoom in/out buttons
• Theme Toggle: Switch between dark/light themes
• Autoplay Progress: Show progress bar during autoplay
• Download Button: Download image button
• Share Button: Share link button

Thumbnail Settings

• Thumbnail Height: Height of thumbnails in strip (20-200px, default: 60)
• Thumbnail Style: Crop (fixed ratio) or Natural (variable width)

Autoplay Settings

• Autoplay Interval: Time between slides in milliseconds (100-60000, default: 3000)
• Users can pause/resume autoplay using the play/pause button
• Speed can be adjusted using the speed slider

Caption Settings

• Enable Captions in Modal: Show image titles and descriptions in modal
• Captions appear below the image in the modal
• Supports both title (main caption) and description (sub-caption)

Navigation

Users can navigate images using:

• Arrow buttons (left/right)
• Keyboard arrow keys
• Swipe gestures on mobile
• Thumbnail strip clicks
• ESC key to close modal

Thumbnail Resizing

Automatically resize images for gallery thumbnails:

• Thumbnail Width: Width in pixels (leave empty to use original size)
• Thumbnail Height: Height in pixels (leave empty to maintain aspect ratio)
• If only width is set, height maintains aspect ratio
• If only height is set, width maintains aspect ratio
• If both are set, image is resized to fit (may crop)

Example: Width: 300, Height: 200 creates 300x200 thumbnails.

Modal Image Resizing

Resize images displayed in the modal/lightbox:

• Modal Image Width: Width in pixels (leave empty to use original size)
• Modal Image Height: Height in pixels (leave empty to maintain aspect ratio)
• Larger dimensions for better quality in modal view
• Recommended: 1200-1800px width for optimal balance

Image Caching

Resized images are automatically cached:

• First request: Image is resized and saved to cache
• Subsequent requests: Cached version is used for faster loading
• Cache location: images/cache/vertexgallery/
• Cache is automatically managed - no manual cleanup needed
• If original image changes, cache is regenerated

WebP Conversion

Convert resized images to WebP format for better performance:

• Enable WebP Format: Turn WebP conversion on/off
• WebP Quality: Quality setting from 1-100 (default: 85)
• Higher quality = larger files but better image quality
• Lower quality = smaller files but reduced image quality
• Recommended: 80-90 for optimal balance

Benefits: WebP images are typically 25-30% smaller than JPEG/PNG while maintaining similar quality, resulting in faster page loads.

Requirements

For image resizing and WebP conversion:

• PHP GD extension must be installed and enabled
• For WebP: PHP GD must support WebP format (PHP 7.1+)
• Check PHP info to verify GD and WebP support

Best Practices

• Set thumbnail dimensions based on your layout (e.g., 300px for 3-column grid)
• Use modal resizing to limit large image sizes (e.g., max 1800px width)
• Enable WebP for better performance, especially on mobile
• Test quality settings to find optimal balance for your images
• Monitor cache folder size if you have many images

Gallery Captions

Control when and how captions are displayed:

• Show Gallery Caption:
  • Always: Captions always visible below images
  • On Hover: Captions appear when hovering over images
  • Hide: Captions are hidden in gallery view
• Captions can include both title (main) and description (sub-caption)
• Modal captions are controlled separately via "Enable Captions in Modal" setting

Image Filters

Apply visual filters to gallery images:

• Image Filter: None, Grayscale, Sepia, Blur, Brightness, Contrast, Saturate
• Filter Amount: Intensity (0-100 for grayscale/sepia, 0-200 for others)
• Filter on Hover:
  • Remove Filter on Hover: Filtered images show in color on hover
  • Add Filter on Hover: Images get filtered on hover
  • No Hover Effect: Filter remains constant

Category Filtering

• Show Gallery Filter: Enable/disable filter buttons
• Categories come from folder names, subfolder names (when enabled), multi-folder paths, or slide categories
• Filter buttons appear at the top of the gallery
• "All" shows every image; other buttons show one category

Gallery Behavior

• Randomize Gallery Order: Randomize image order on each page load
• Show Single Image Preview: Show one image initially, expand to full gallery on click

Module Suffix & Extra CSS

• Add a module class suffix for targeted styling
• Use Extra CSS with placeholders {module_id} and {gallery_id}
• Example: #vg-mod-{module_id} { background: #f0f0f0; }

Note: Extra CSS is for styling only. Do not put gallery shortcodes in CSS fields.

Multiple Galleries on One Page

• Create multiple module instances with different configurations
• Use multiple shortcodes in articles
• Each gallery operates independently with its own settings

Multi-Category Folder Setup

Module (easiest): Parent path + Use Subfolders as Filters = Yes.

Module (explicit): Comma-separated paths or path|Label entries in Image Folder Path.

Plugin shortcode:

{vertexgallery folders="images/gallery/Animals|Animals,images/gallery/Teams|Teams"}

Custom Category Names

• Slides: enter the category on each slide
• Folders: use folder names, or folder|Custom Label
• Categories are case-sensitive — keep naming consistent

Plugin Default Settings

• Go to System > Plugins > Content - Vertex Gallery
• Set defaults for layout, columns, modal, etc.
• Shortcode attributes override plugin defaults

Performance Optimization

• Enable WebP conversion for smaller file sizes
• Set appropriate thumbnail and modal image sizes
• Use folder-based loading for large collections
• Resized images are cached automatically

Template Overrides

1. Copy modules/mod_vertexgallery/tmpl/default.php
2. To: templates/your-template/html/mod_vertexgallery/default.php
3. Modify as needed

Only "All" and "Gallery" Filters Appear

• You are pointing at the parent folder (e.g. images/gallery) with Use Subfolders as Filters turned off
• Creating subfolders alone does not create filters — enable the option, or list each subfolder path
• Images inside nested subfolders are ignored unless that folder is the configured path (or a listed path / immediate subfolder when the option is on)

Gallery Not Displaying

• Check Module Status: Published and assigned to the current page
• Verify Image Source: Folder path correct or slides configured
• Check Image Paths: Relative to Joomla root
• Cache: Clear Joomla and browser cache

Images Not Loading

• Use relative paths (e.g. images/gallery), not absolute URLs
• Folder must be readable; only JPG, JPEG, PNG, GIF, WebP
• Confirm files exist on the server

Shortcode Not Processing

• Plugin enabled: Content - Vertex Gallery
• Shortcode is in an article or Custom HTML module — not in CSS
• Syntax: {vertexgallery ...} with quoted attributes

Category Filtering Issues

• Enable Show Gallery Filter
• For subfolders: enable Use Subfolders as Filters on the parent path
• Or use folders= / comma-separated paths
• Check category spelling and case

Modal / Layout / Performance

• Enable Modal set to Yes; check browser console for JS errors
• Column format: auto, number, or "1,2,3"
• Enable resizing and WebP for large galleries; ensure PHP GD is available

• I created subfolders (Animals, Teams, Farm Shop) inside gallery, but I only see "All" and "Gallery". Why?

  • Category filters come from the folder path you configure, not from nested folders by default. Point the module at images/gallery, turn Use Subfolders as Filters to Yes, and enable Show Gallery Filter. Or list each subfolder path explicitly.

• Where can I insert the shortcode? Do I put it in CSS?

  • No — never put the shortcode in CSS. Paste it into an article or a Custom HTML module. CSS is only for styling.

• I am using the Vertex Gallery module. Do I still need a shortcode?

  • No. Configure everything in the module (folder path, Use Subfolders as Filters, Show Gallery Filter). Shortcodes are for the content plugin when you embed a gallery in article text.

• How do I get multiple category filters with the module?

  • Easiest: parent folder + Use Subfolders as Filters = Yes. Alternative: comma-separated folder paths, or Slides mode with a Category on each image.

• What does Use Subfolders as Filters do?

  • It scans each immediate subfolder of your Image Folder Path and uses the subfolder name as a category filter. Deeper nested folders are not scanned. Images in the parent folder keep the parent name as their category.

• How do I use multiple folders with a shortcode?

  • Use folders=, for example: {vertexgallery folders="images/gallery/Animals|Animals,images/gallery/Teams|Teams,images/gallery/Farm Shop|Farm Shop"}

• What's the difference between the Module and Plugin?

  • The Module displays galleries in module positions with backend settings. The Plugin embeds galleries in articles via shortcodes. Both use the same gallery engine.

• Can I use both folder-based and manual slides in one gallery?

  • One source type per gallery. You can place multiple galleries (module and/or shortcode) on the same page.

• Do I need to enable the plugin if I only use the module?

  • No. The plugin is only required for shortcodes (and the editor button uses the content plugin ecosystem for insertion).

• How do categories work?

  • Folder mode: from folder/subfolder names or path|Label. Slides mode: category field on each slide. Filters appear when Show Gallery Filter is enabled.

• Can I resize images automatically / use WebP?

  • Yes — Image Resize Settings for thumbnail/modal sizes and optional WebP conversion (requires PHP GD).

• Can I have multiple galleries on one page?

  • Yes — multiple module instances and/or multiple shortcodes, each with its own settings.

• Why aren't my images showing?

  • Check relative paths, that files exist, folder permissions, supported extensions (JPG, PNG, GIF, WebP), and clear cache.

• Can I use shortcodes in modules?

  • Yes, in a Custom HTML module — not inside the Vertex Gallery module's CSS field.

• Is Vertex Gallery compatible with Joomla 5 and 6?

  • Yes — Joomla 4, 5, and 6.