Get Started

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
• Grid and Masonry layouts with responsive column controls
• Advanced modal lightbox with dark/light themes and comprehensive controls
• Folder-based or manual slide management
• 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 both the module and plugin. 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

Both components are automatically installed and the plugin is enabled by default:

• Module: Go to Content > Site Modules and create a new "Vertex Gallery" module instance
• Plugin: Go to Extensions > Plugins and find "Content - Vertex Gallery" to configure default settings

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 both components are installed:

1. Check Extensions > Manage > Manage - you should see both "mod_vertexgallery" and "plg_content_vertexgallery"
2. Verify plugin is enabled in Extensions > Plugins
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 (see tabs below for details)
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

The module has 6 configuration tabs:

• Image Source: Choose folder-based or manual slides, configure image sources
• Layout & Visual: Layout style, columns, gaps, visual themes, filters
• 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

Module Positions

Assign the module to any available module position in your template. Common positions include:

• Sidebar positions (left, right)
• Header/Footer positions
• Content top/bottom
• Custom module positions

Multiple Instances

You can create multiple gallery module instances, each with unique configurations. Each gallery gets a unique ID (vg-mod-{module_id}) for targeted styling and CSS customization.

Basic Shortcode Syntax

The Content Plugin uses simple shortcode syntax to display galleries in articles:

{vertexgallery folder="images/gallery"}

or

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

Shortcode Attributes

Available attributes for the shortcode:

• folder - Path to folder containing images (e.g., "images/gallery")
• images - Comma-separated list of image paths (e.g., "img1.jpg,img2.jpg")
• layout - Gallery layout: "grid" or "masonry" (default: from plugin settings)
• columns - Number of columns: "auto", number, or "1,2,3" for responsive (default: from plugin settings)
• gap - Gap between items in pixels (default: 16)
• show_filter - Show category filter buttons: "1" or "0" (default: 1)
• enable_modal - Enable lightbox modal: "1" or "0" (default: 1)
• modal_theme - Modal theme: "dark" or "light" (default: dark)

Shortcode Examples

{vertexgallery folder="images/portfolio"}

{vertexgallery images="images/photo1.jpg,images/photo2.jpg,images/photo3.jpg"}

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

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

Where to Use Shortcodes

You can use shortcodes in:

• Articles: Add shortcodes directly in article content
• Custom HTML Modules: Use in module content
• Category Descriptions: Add in category descriptions
• Menu Items: Use in menu item descriptions
• Any Content Area: Anywhere that supports HTML content

Multiple Galleries

You can use multiple shortcodes on the same page, each with different configurations:

{vertexgallery folder="images/gallery1"}

{vertexgallery folder="images/gallery2" layout="masonry"}

Folder-Based Images

Automatically load all images from a specified folder:

1. In module: Set Image Source Type to "Folder"
2. Enter Image Folder Path (e.g., "images/gallery" or "images/photos")
3. Optionally enable Auto-Generate Titles from Filenames

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

Category Assignment: Categories are automatically generated from folder names (e.g., "images/forest" becomes "Forest")

Manual Slides

Manually add individual images with custom metadata:

1. In module: Set Image Source Type to "Slides"
2. Click Add in the Gallery Slides subform
3. For each slide, configure:
   • Image: Select or upload image
   • Title: Main caption (optional)
   • Description: Sub-caption (optional)
   • Category: Category for filtering (optional, defaults to "default")
4. Add multiple slides as needed

Advantages: Full control over each image's title, description, and category. Perfect for curated galleries with specific metadata.

Image Paths

Image paths are relative to Joomla root directory:

• Correct: images/gallery/photo.jpg
• Correct: images/vertex/image-19-large.jpg
• Incorrect: /images/gallery/photo.jpg (leading slash)
• Incorrect: http://example.com/images/photo.jpg (absolute URL)

Joomla Media Field

When using manual slides, the image field uses Joomla's media field. The field may include a reference after # (e.g., "images/photo.jpg#joomlaImage://..."). The system automatically extracts the correct path.

Best Practices

• Organize images in dedicated folders (e.g., images/gallery, images/portfolio)
• Use descriptive filenames if auto-generating titles
• For large collections, use folder-based loading
• For curated galleries, use manual slides with custom metadata
• Keep image file sizes reasonable for better 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

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

Organize and filter images by category:

• Show Gallery Filter: Enable/disable filter buttons
• Categories are automatically generated from folder names (folder-based) or manually assigned (slides)
• Filter buttons appear at the top of the gallery
• Clicking a category button filters images to show only that category
• "All" button shows all images

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

Add custom CSS class to gallery wrapper:

• Enter suffix in Advanced tab (e.g., "custom-gallery")
• Results in class: vertex-gallery-wrapper custom-gallery
• Use for targeted CSS styling

Extra CSS

Add custom CSS code per module instance:

• Enter CSS in Advanced tab
• Use placeholders: {module_id} and {gallery_id}
• Example: #vg-mod-{module_id} { background: #f0f0f0; }
• Placeholders are automatically replaced with actual IDs

CSS Targeting

Target specific galleries using unique IDs:

/* Target specific gallery */
#vg-mod-123 {
  max-width: 1200px;
  margin: 0 auto;
}

/* Target all galleries */
.vertex-gallery-wrapper {
  padding: 20px;
}

/* Target filter buttons */
.vertex-gallery-filter-btn {
  background: #007bff;
  color: white;
}

Multiple Galleries on One Page

You can display multiple galleries on the same page:

• Create multiple module instances with different configurations
• Use multiple shortcodes in articles
• Each gallery operates independently with its own settings
• Each gallery gets a unique ID for targeted styling

Responsive Column Configuration

Set different column counts for different screen sizes:

• Format: "mobile,tablet,desktop" (e.g., "1,2,4")
• Example: "1,2,3" means 1 column on mobile, 2 on tablet, 3 on desktop
• Breakpoints are automatically handled by the gallery
• Use "auto" for automatic column calculation

Combining Folder and Manual Slides

While you can only use one source type per gallery, you can:

• Create multiple galleries with different source types
• Use folder-based for bulk images
• Use manual slides for featured/curated content
• Display both on the same page

Custom Category Names

For manual slides, assign custom category names:

• Enter any category name in the slide's category field
• Categories are case-sensitive
• Use consistent naming for proper filtering
• Leave empty to use "default" category

For folder-based images, categories are generated from folder names (e.g., "images/forest" → "Forest").

Plugin Default Settings

Configure default settings in plugin configuration:

• Go to Extensions > Plugins > Content - Vertex Gallery
• Set default layout, columns, modal settings, etc.
• These defaults apply to all shortcode instances
• Shortcode attributes can 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 (more efficient)
• Limit modal image width to reduce bandwidth
• Resized images are cached automatically

Integration with Other Extensions

Vertex Gallery works well with:

• Custom HTML modules (use shortcodes)
• Article content (use shortcodes)
• Template overrides (customize template files)
• Third-party modules (embed via Custom HTML)

Template Overrides

To customize the gallery template:

1. Copy modules/mod_vertexgallery/tmpl/default.php
2. To: templates/your-template/html/mod_vertexgallery/default.php
3. Modify as needed
4. Your template override will be used instead of the default

Gallery Not Displaying

• Check Module Status: Ensure module is published and assigned to current page
• Verify Image Source: Check folder path is correct or slides are configured
• Check Image Paths: Ensure images exist at specified paths (relative to Joomla root)
• JavaScript Errors: Check browser console (F12) for JavaScript errors
• Asset Loading: Verify CSS and JS files are loading (check Network tab)
• Cache Issues: Clear Joomla cache and browser cache

Images Not Loading

• Path Format: Use relative paths (e.g., "images/gallery"), not absolute URLs
• Folder Permissions: Ensure folder is readable by web server
• File Extensions: Only JPG, JPEG, PNG, GIF, WebP are supported
• Joomla Media Field: If using manual slides, check image field contains valid path
• Check File Existence: Verify images actually exist at specified locations

Modal Not Working

• Enable Modal: Check "Enable Modal" is set to Yes
• JavaScript Errors: Check browser console for errors
• Asset Loading: Verify vertex-gallery.js is loaded
• Click Events: Ensure images are clickable (check z-index and CSS)
• Touch Support: On mobile, ensure swipe gestures are working

Image Resizing Issues

• PHP GD Extension: Verify GD extension is installed (check PHP info)
• WebP Support: For WebP conversion, ensure GD supports WebP (PHP 7.1+)
• Cache Permissions: Ensure cache folder (images/cache/vertexgallery/) is writable
• Memory Limit: Large images may require increased PHP memory_limit
• Check Cache: Clear cache folder if resized images are incorrect

Layout Problems

• Columns Not Working: Check column format (auto, number, or "1,2,3")
• Masonry Issues: Ensure JavaScript is loaded and no conflicts
• Responsive Issues: Test on different screen sizes, check CSS conflicts
• Gap Issues: Verify gap value is numeric (pixels)

Shortcode Not Processing

• Plugin Enabled: Verify "Content - Vertex Gallery" plugin is enabled
• Syntax: Check shortcode syntax is correct: {vertexgallery ...}
• Attributes: Verify attribute format: attribute="value" (quotes required)
• Context: Shortcodes work in articles, not in all contexts

Category Filtering Issues

• Show Filter: Ensure "Show Gallery Filter" is enabled
• Categories: Verify images have categories assigned
• Category Names: Check for typos or case sensitivity issues
• Folder Names: For folder-based, categories come from folder names

Performance Issues

• Too Many Images: Consider pagination or limiting number of images
• Large Images: Enable image resizing to reduce file sizes
• WebP: Enable WebP conversion for better performance
• Cache: Ensure image cache is working properly
• CDN: Consider using CDN for image delivery

Browser Compatibility

Vertex Gallery works with:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

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

  • The Module displays galleries in module positions with full backend configuration. The Plugin allows embedding galleries in articles using shortcodes. Both share the same gallery engine.

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

  • You can only use one source type per gallery, but you can create multiple galleries with different source types on the same page.

• How do I find the module ID for CSS targeting?

  • The module ID is shown in the module list (Content > Site Modules) or in the module edit URL. The gallery ID format is vg-mod-{module_id}.

• Can I customize the gallery appearance?

  • Yes! Use module suffix, extra CSS field, or template overrides. You can also customize colors, filters, corner styles, and more in the module settings.

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

  • No, the module works independently. The plugin is only needed if you want to use shortcodes in articles.

• How do categories work?

  • For folder-based images, categories are generated from folder names. For manual slides, you assign categories manually. Use the filter buttons to show images by category.

• Can I resize images automatically?

  • Yes! Set thumbnail and modal image dimensions in the Image Resize Settings tab. Images are automatically resized and cached.

• What is WebP conversion?

  • WebP is a modern image format that provides 25-30% smaller file sizes than JPEG/PNG. Enable it in Image Resize Settings for better performance.

• Can I have multiple galleries on one page?

  • Yes! Create multiple module instances or use multiple shortcodes. Each gallery operates independently with its own configuration.

• How do I disable the modal/lightbox?

  • Set "Enable Modal" to No in the Modal/Lightbox Settings tab. Images will still be clickable but won't open in a modal.

• Why aren't my images showing?

  • Check image paths are correct (relative to Joomla root), images exist at those paths, folder permissions are correct, and file extensions are supported (JPG, PNG, GIF, WebP).

• Can I use shortcodes in modules?

  • Yes! Use shortcodes in Custom HTML modules. The plugin processes shortcodes in any content area.

• How do I change the gallery layout?

  • In module: Set Layout to Grid or Masonry in Layout & Visual tab. In shortcode: Use layout="grid" or layout="masonry" attribute.

• What browsers are supported?

  • Vertex Gallery works with all modern browsers including Chrome, Firefox, Safari, Edge, and mobile browsers. Requires JavaScript enabled.

• Can I use this with Joomla 5 or 6?

  • Yes! Vertex Gallery is fully compatible with Joomla 4, 5, and 6 using modern coding standards and WebAssetManager.