Woomark Image Gallery - JoomlaX Documentation

Introduction

Wookmark Image Gallery is a powerful Joomla extension that creates beautiful masonry-style image galleries with lightbox functionality. Available as both a Content Plugin and Module, it provides flexible options for displaying image galleries throughout your Joomla website.

Plugin vs Module

Content Plugin: Use shortcodes directly in articles and content areas to create galleries inline with your content
Module: Display galleries in module positions (sidebars, headers, footers, etc.) with advanced configuration options

Key Highlights:

Full Joomla 4, 5 & 6 Compatibility
Masonry/Pinterest-style Grid Layout
Fancybox Lightbox Integration
Automatic Image Resizing & Caching
WebP Format Support
Built-in Shortcode Examples (Plugin)
Folder-based or Individual Image Selection
Multiple Sorting Options
Fully Responsive Design

Installation

Downloading the Extension

After purchasing the extension, you will receive download links for both the plugin and module packages.

Installing the Plugin

Log in to your Joomla backend
Navigate to Extensions > Manage > Install
Click on the "Upload Package File" tab
Select the plugin installation file (plg_content_wookmark_gallery_X.x.zip)
Click "Upload and Install"
Navigate to Extensions > Plugins
Search for "Content - Woomark Image Gallery" and enable it

Installing the Module

Navigate to Extensions > Manage > Install
Click on the "Upload Package File" tab
Select the module installation file (mod_wookmark_gallery_X.x.zip)
Click "Upload and Install"
Navigate to Extensions > Modules
Click "New" and select "Woomark Image Gallery"
Configure and publish the module

A success message will be displayed once the installation is complete.

Plugin Settings

Access plugin settings by navigating to Extensions > Plugins, and find Content - Woomark Image Gallery.

Image Settings

Thumb Image Width: Width of thumbnail images in pixels (default: 150)
Large Image Width: Width of large images displayed in lightbox (default: 800)
Enable WebP: Convert images to WebP format for better performance (default: False)
Large Image Caption: Enable/disable captions for large images (default: Disable)
Caption Position: Position of captions (Float, Inside, Outside, Over) - only when caption is enabled
Offset: Distance between grid items in pixels (default: 2)

Styling Settings

Background Color: Background color of the lightbox overlay (default: rgba(0, 0, 0, 0.7))
Opening Speed: Animation speed when opening lightbox in milliseconds (default: 500)
Closing Speed: Animation speed when closing lightbox in milliseconds (default: 500)
Shadow Color: Shadow color of the fancybox (default: #000)
Shadow Width: Width of the fancybox shadow (default: 50)
Show Close Button: Display close button in lightbox (default: Yes)
FancyBox Border Width: Border width around images in lightbox (default: 5)
Opening And Closing Effect: Animation effect (None, Elastic, Fade) - default: Elastic

Module Settings

Access module settings by navigating to Extensions > Modules, create or edit a "Woomark Image Gallery" module.

Image Settings

Fetch Image: Choose how to load images
- From Folder: Automatically load all images from a folder
- Individual Path: Manually select specific images
Image Folder Path: Path to folder containing images (e.g., images/gallery/) - only when "From Folder" is selected
Sort Images: How to sort images
- Sequence A-Z: Alphabetical order
- Sequence Z-A: Reverse alphabetical order
- Random: Random order each page load
Thumb Image Width: Width of thumbnail images (default: 150)
Large Image Width: Width of large images in lightbox (default: 800)
Enable WebP: Convert images to WebP format (default: False)
Caption: Display captions (For Large Image Only, For Thumb Image Only, For Both, None) - only when "Individual Path" is selected
Link: Enable/disable links on images - only when "Individual Path" is selected
Open In: Link target (_self or _blank) - only when links are enabled
Grid Spacing: Distance between grid items in pixels (default: 2)

Styling Settings

Same options as plugin (Background Color, Opening/Closing Speed, Shadow, Close Button, Border Width, Effects)

Advanced Settings

Module Class Suffix: Add custom CSS class suffix for styling

Plugin Usage

Shortcode Examples Tab

The plugin includes a built-in Shortcode Examples tab in the plugin configuration with ready-to-use examples. Simply click "Copy" on any example to copy it to your clipboard, then paste it into your content.

Basic Syntax

Gallery from Folder

Display all images from a specific folder:

{wookmark folder="images/gallery"}

Individual Images Gallery

Display specific images with titles:

{wookmark image1="images/photo1.jpg" title="Photo 1" image2="images/photo2.jpg" title="Photo 2" image3="images/photo3.jpg" title="Photo 3"}

Multiple Images

Gallery with multiple individual images:

{wookmark image1="images/product1.jpg" title="Product 1" image2="images/product2.jpg" title="Product 2" image3="images/product3.jpg" title="Product 3" image4="images/product4.jpg" title="Product 4"}

Gallery in Article Content

Embed gallery within article text:

<p>Check out our gallery: {wookmark folder="images/gallery"} Enjoy the photos!</p>

Where to Use

You can add shortcodes in:

Joomla articles (Article Editor)
Custom HTML modules
Any content area that supports HTML

Image Path Guidelines

Use relative paths from your Joomla root (e.g., images/gallery/photo.jpg)
Do not include leading slash in image paths
Supported formats: JPG, JPEG, PNG, GIF
Images are automatically resized according to your plugin settings
Resized images are cached in images/wookmark/ directory

Module Usage

Creating a Gallery Module

Step 1: Create New Module

Navigate to Extensions > Modules
Click "New" button
Select "Woomark Image Gallery" from the list

Step 2: Configure Gallery Source

Option A: From Folder

Set "Fetch Image" to "From Folder"
Enter folder path (e.g., images/gallery/)
All images in the folder will be automatically included
Configure sorting (A-Z, Z-A, or Random)

Option B: Individual Images

Set "Fetch Image" to "Individual Path"
Click "Add" button to add slides
For each slide:
- Select an image
- Add caption (optional)
- Add link URL (optional)
Configure caption display options
Configure link options and target

Step 3: Configure Display Settings

Set thumbnail and large image widths
Enable WebP if desired
Configure grid spacing
Set styling options (colors, speeds, effects)

Step 4: Assign Module Position

Select module position (sidebar, header, footer, etc.)
Set menu assignment (all pages, specific pages, etc.)
Add module class suffix for custom styling (optional)

Step 5: Publish

Set status to "Published"
Save the module
View your website to see the gallery

Module Positions

Common module positions where galleries work well:

Sidebar positions: left, right, sidebar-a, sidebar-b
Content positions: above-content, below-content
Footer positions: footer, footer-a, footer-b
Custom positions: Any custom module position in your template

Features

Core Features

Masonry Grid Layout: Beautiful Pinterest-style masonry grid that automatically arranges images for optimal display
Fancybox Lightbox: Professional lightbox overlay for viewing large images with smooth animations
Automatic Image Resizing: Automatically resize images for thumbnails and lightbox display with configurable dimensions
Smart Image Caching: Automatically cache resized images for faster repeated loads and improved performance
WebP Format Support: Optional WebP format conversion for smaller file sizes and faster loading times
Multiple Image Sources: Load images from folders or manually select individual images
Flexible Sorting: Sort images alphabetically, reverse alphabetically, or randomly
Built-in Shortcode Examples: Plugin includes ready-to-use shortcode examples with one-click copy

Plugin-Specific Features

Inline Content Integration: Add galleries directly in articles using simple shortcodes
Folder-based Galleries: Automatically display all images from a folder with one shortcode
Individual Image Control: Specify individual images with custom titles
Content Context Aware: Only processes shortcodes in appropriate content contexts

Module-Specific Features

Module Position Flexibility: Display galleries anywhere on your site using module positions
Advanced Configuration: More granular control over image display, captions, and links
Subform Interface: Easy-to-use interface for adding multiple images with captions and links
Menu Assignment: Control which pages display the gallery module
Module Class Suffix: Add custom CSS classes for advanced styling

Advanced Features

Performance Optimized: Uses Joomla's WebAssetManager for optimal asset loading
Mobile Responsive: Fully responsive design that works perfectly on all devices
Customizable Styling: Extensive styling options for colors, speeds, effects, and spacing
Image Quality Control: Configurable image quality settings for optimal balance between quality and file size

Compatibility

Joomla 4, 5 & 6 Compatible: Full support for all modern Joomla versions
Modern PHP: PHP 7.4+ syntax and features for better performance
Future-Proof: Regular updates and security patches for long-term compatibility

FAQ

General Questions

What's the difference between the plugin and module?

Plugin: Use shortcodes in articles/content to create galleries inline with your content
Module: Display galleries in module positions (sidebars, headers, etc.) with more configuration options
Both use the same underlying technology and styling options

Which Joomla versions are supported?

Both plugin and module are fully compatible with Joomla 4.x, 5.x, and 6.x

What image formats are supported?

JPG, JPEG, PNG, GIF formats are supported
WebP conversion is available as an optional feature
Images are automatically resized according to your settings

Plugin Questions

How do I add a gallery to an article?

Use the shortcode: {wookmark folder="images/gallery"} for folder-based galleries
Or use: {wookmark image1="images/photo1.jpg" title="Photo 1"} for individual images
See the Shortcode Examples tab in plugin settings for more examples

Can I use both folder and individual images in one shortcode?

No, you need to use separate shortcodes for each gallery type
You can use multiple shortcodes in the same article

Module Questions

How do I create a gallery module?

Go to Extensions > Modules > New
Select "Woomark Image Gallery"
Choose "From Folder" or "Individual Path"
Configure images and settings
Assign to a module position and publish

Can I display captions on images?

Yes, when using "Individual Path" mode, you can add captions to each image
Choose caption display: For Large Image Only, For Thumb Image Only, For Both, or None
Folder-based galleries don't support captions

Can images link to external URLs?

Yes, when using "Individual Path" mode, you can add a link URL to each image
Set link target to open in same window or new tab
If no link is provided, images open in lightbox

Technical Questions

How does image caching work?

Resized images are cached in images/wookmark/ directory
This improves performance by avoiding repeated image processing
Cache is automatically created when images are first processed

How do I enable WebP support?

Enable "WebP" option in Image Settings (both plugin and module)
Images will be converted to WebP format automatically
Original images remain unchanged
Requires WebP support on your server

Can I customize the gallery styling?

Yes, extensive styling options are available in settings
For modules, use Module Class Suffix to add custom CSS
Gallery uses standard CSS classes that can be overridden

Troubleshooting

Common Issues and Solutions

Plugin Issues

Shortcodes Not Working

Ensure the plugin is enabled in Extensions > Plugins
Verify the shortcode syntax is correct
Check that you're using the correct shortcode format: {wookmark folder="..."} or {wookmark image1="..."}
Clear Joomla cache and browser cache
Check browser console for JavaScript errors

Images Not Displaying

Verify the image path is correct (relative to Joomla root, no leading slash)
Check that the image file exists and is readable
Ensure the image format is supported (JPG, PNG, GIF)
Check file permissions on the images directory
Verify the folder path is correct for folder-based galleries

Module Issues

Module Not Displaying

Ensure the module is published
Check module position is correct for your template
Verify menu assignment includes the current page
Check that module is assigned to correct user groups
Clear Joomla cache

Images Not Loading in Module

Verify folder path is correct (for folder-based galleries)
Check that images exist in the specified folder
For individual images, verify image paths are correct
Check file permissions on images directory
Ensure images are in supported formats

Image Processing Issues

Images Not Resizing Properly

Check thumbnail and large image width settings
Ensure the cache directory is writable: images/wookmark/
Clear the image cache by deleting files in the cache directory
Check PHP GD or ImageMagick is installed and enabled
Verify image files are not corrupted

WebP Conversion Not Working

Ensure your server supports WebP format
Check PHP GD or ImageMagick has WebP support
Verify WebP support is enabled in PHP
Check server error logs for conversion errors
Test with a simple image first

Lightbox Issues

Lightbox Not Opening

Check that jQuery is loaded (included with Joomla by default)
Verify Fancybox JavaScript files are loading (check browser console)
Check for JavaScript errors in browser console
Ensure no other scripts are conflicting
Clear browser cache

Lightbox Styling Issues

Check Fancybox CSS files are loading
Verify no CSS conflicts with your template
Check browser console for CSS errors
Try disabling other plugins/modules temporarily

Performance Issues

Gallery Loading Slowly

Enable WebP format for smaller file sizes
Reduce thumbnail and large image widths
Ensure image caching is working (check cache directory)
Optimize source images before uploading
Consider using fewer images per gallery

Getting Help

If you continue to experience issues:

Check Joomla error logs for PHP errors
Visit our support forum: https://support.joomlax.com
Ensure you're using the latest version
Verify your Joomla version is compatible (4.x, 5.x, or 6.x)
Check documentation: https://joomlax.com/documentation/woomark-image-gallery