jQuery Thumbnail Scroller - JoomlaX Documentation

Introduction

jQuery Thumbnail Scroller is a powerful and flexible Joomla module that creates an elegant horizontal thumbnail scroller with lightbox integration. Perfect for showcasing image galleries, portfolios, or product images, this module provides smooth scrolling animations and professional presentation.

Fully compatible with Joomla 4, 5, and 6, the jQuery Thumbnail Scroller offers extensive customization options including click-based navigation, auto-scroll functionality, lightbox integration, flexible image sources, and fully responsive design.

This documentation covers the installation, configuration, and usage of the jQuery Thumbnail Scroller module.

Installation

Downloading the Extension

Email: After you purchase the extension from our store, you will receive an email containing a link to download the extension.

Store: Alternatively, you can download the extension from the Downloads section of our store. If you are a new user, you need to create an account using the same email address you used for the purchase.

Click to download the extension package: jQueryThumbnailScroller_UNZIP.zip

Unzipping the Package

Use any file unzipper tool or WinRAR to unzip the jQueryThumbnailScroller_UNZIP.zip package. After unzipping, you will find the following contents:

Folder Joomla 4, 5 & 6: This extension is compatible with Joomla 4.x, 5.x, and 6.x. In this folder, you will find the installation file named mod_thumbnail_scroller_X.x.zip.
ReadMe.txt: Contains vital information about the current version of the extension.

Installing the Extension

To install the extension, log in to the backend of your Joomla website.

For Joomla 4, 5 & 6: Go to System > Install > Extensions. You can either drag and drop or browse for the file to install.

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

After successful installation:

Go to Content > Site Modules
You will find jQuery Thumbnail Scroller listed. Click on it to configure.

Scroller Settings

Configure the basic scroller settings in the Scroller Settings tab.

Scroller Dimensions

Scroller Width: Set the width of the thumbnail scroller. You can use pixels (e.g., 300px) or percentage (e.g., 100%). Enter only the number for pixels or include % for percentage.
Thumbnail Height (pixels): Set the height of thumbnail images in pixels. This determines the vertical size of each thumbnail in the scroller. Enter only the number without 'px'.

Scrolling Configuration

Scrolling Speed (milliseconds): Set the scrolling speed in milliseconds. Lower values create faster scrolling. 1000 milliseconds = 1 second. Recommended range: 300-1000ms.

Auto-Scroll Settings

Auto Scrolling Loops: Set the number of auto-scrolling loops. 0 means infinite looping. Enter a positive number to limit the number of loops.
Auto Scrolling Speed (milliseconds): Set the initial auto-scrolling speed in milliseconds. This controls how fast the scroller moves during auto-scroll. 1000 milliseconds = 1 second. Recommended range: 3000-10000ms.
Auto Scrolling Delay (milliseconds): Set the delay between auto-scrolling loops in milliseconds. This is the pause time before the next loop begins. 1000 milliseconds = 1 second. Recommended range: 1000-5000ms.
Note: Auto-scroll automatically pauses when users hover over the scroller and resumes when they move away.

Lightbox Settings

Configure the lightbox settings for viewing full-size images.

Lightbox Configuration

Opening Speed (milliseconds): Set the animation speed when opening images in the lightbox in milliseconds. Lower values create faster animations. Recommended range: 300-1000ms.
Closing Speed (milliseconds): Set the animation speed when closing images in the lightbox in milliseconds. Lower values create faster animations. Recommended range: 300-1000ms.
Lightbox Background Color: Set the background color of the overlay when images are opened in the lightbox. Use hexadecimal color codes (e.g., #000000 for black, #FFFFFF for white) or RGBA for transparency.
Lightbox Transition Effect: Choose the animation effect when opening and closing images in the lightbox. None: Instant open/close. Elastic: Smooth elastic animation. Fade: Smooth fade in/out transition.
Lightbox Border Width (pixels): Set the border width around images in the lightbox in pixels. Enter 0 to remove the border completely. Recommended range: 0-20px.
Show Close Button: Display a close button in the lightbox. When enabled, users can click the button to close the lightbox. When disabled, users must click outside the image or press ESC to close.

Image Settings

Configure how images are loaded into the scroller.

Image Source

Image Source: Choose how images are loaded into the scroller. From Folder: Automatically load all images from a specified folder. Individual Images: Manually select individual images using a repeatable list.

Folder-Based Images

Image Folder Path: Enter the path to the folder containing your images, relative to the Joomla root directory. Example: images/gallery/ or images/scroller/. Only image files (jpg, jpeg, png, gif, webp) in this folder will be displayed in the scroller.
Note: This option is only available when Image Source is set to From Folder.

Individual Images

Individual Images: Click the Add button to add images individually. For each item, select an image and optionally enter a title/alt text.
Note: This option is only available when Image Source is set to Individual Images.

Image Processing

Images are automatically resized to the Thumbnail Height you specify using Joomla's Image class.
Resized thumbnails are cached in the images/mod_thumbnail_scroller_cache folder for improved performance.
Thumbnails maintain original image aspect ratios for consistent display.

Features

Once configured, assign the module to a position on your Joomla template and publish it. The jQuery Thumbnail Scroller will display images in a scrolling gallery format based on your settings, providing a dynamic and engaging visual experience.

Key Features

Click-Based Navigation: Simple and intuitive navigation using previous and next arrow buttons with smooth scrolling animations.
Hover-Reveal Buttons: Navigation buttons appear on hover for desktop users, always visible on mobile and tablets for better usability.
Auto-Scroll Feature: Automatically scroll through thumbnails with configurable loops, speed, and delay. Pauses on hover for better user control.
Lightbox Integration: Click thumbnails to view full-size images in an elegant Fancybox lightbox overlay with customizable effects and gallery navigation.
Smart Image Resizing: Automatic thumbnail generation using Joomla's Image class with intelligent caching for optimal performance.
Flexible Image Sources: Choose between folder-based automatic loading or individual image selection with custom titles.
Fully Responsive Design: Adapts seamlessly to all screen sizes with touch support and mobile-optimized navigation.
Modern Joomla Compatibility: Fully compatible with Joomla 4, 5, and 6 with WebAssetManager integration and PHP 8.0+ support.
Performance Optimized: Lightweight code with unnecessary dependencies removed for faster loading and better performance.
Easy Configuration: Intuitive interface with clear parameter labels and descriptions for quick setup.
Professional Presentation: Navigation arrows, smooth scrolling, and customizable styling for a polished appearance.

FAQ

How do I add images to the scroller?
- You can choose between two methods: 1) Set the Image Source to From Folder and specify the Image Folder Path containing your images. 2) Set the Image Source to Individual Images and use the Add button to select images manually.
How do I navigate through thumbnails?
- Click the previous and next arrow buttons to scroll through thumbnails. On desktop, buttons appear on hover. On mobile and tablets, buttons are always visible.
How do I enable auto-scroll?
- Set Auto Scrolling Loops to a number greater than 0 (or 0 for infinite looping). Configure Auto Scrolling Speed and Delay to customize the auto-scroll behavior. Auto-scroll will automatically pause when users hover over the scroller.
Can I customize the lightbox appearance?
- Yes, under Lightbox Settings, you can customize the background color, border width, transition effects, and close button visibility.
How are thumbnails created?
- Thumbnails are automatically generated from full-size images using Joomla's Image class. They are resized to the Thumbnail Height you specify and cached in the images/mod_thumbnail_scroller_cache folder for performance.
Can I change the scroller width?
- Yes, set the Scroller Width in Scroller Settings. You can use pixels (e.g., 300px) or percentage (e.g., 100%) for responsive layouts.
Does the scroller work on mobile devices?
- Yes, the scroller is fully responsive and includes touch support for mobile devices. Navigation buttons are always visible on mobile and tablets for better usability.
How do I add custom CSS to the scroller?
- Use the Additional CSS field under Advanced Settings to add custom CSS. You can also use the Module Class Suffix to target specific module instances with custom CSS.
What image formats are supported?
- The scroller supports JPG, JPEG, PNG, GIF, and WebP image formats. All images in the specified folder or selected individually will be displayed.
Can I control the scrolling speed?
- Yes, adjust the Scrolling Speed setting in Scroller Settings. Lower values create faster scrolling. Recommended range: 300-1000ms.
Can I add titles to images?
- Yes, when using Individual Images source mode, you can add custom titles/alt text for each image in the subform interface.

Troubleshooting

Scroller Not Displaying: Ensure the module is assigned to a visible template position and published. Verify that you have images configured (either folder path or individual images). Check browser console for JavaScript errors.
No Images Showing: Verify that the Image Source is set correctly. For folder-based: check that the Image Folder Path is correct and that images exist in that folder. For individual: ensure images are selected. Check image file permissions. Ensure images are in supported formats (jpg, jpeg, png, gif, webp).
Thumbnails Not Resizing: Check that the Thumbnail Height is set correctly. Verify that the images/mod_thumbnail_scroller_cache folder is writable. Check browser console for errors.
Auto-Scroll Not Working: Ensure Auto Scrolling Loops is set to a number greater than 0 (or 0 for infinite). Check that Auto Scrolling Speed and Delay values are set correctly. Verify that JavaScript is enabled in the browser.
Lightbox Not Opening: Check that Fancybox JavaScript and CSS files are loading correctly. Verify browser console for JavaScript errors. Ensure jQuery is loaded properly.
Navigation Buttons Not Visible: On desktop, hover over the scroller to see navigation buttons. On mobile and tablets, buttons should always be visible. Check that navigation button images are loading correctly. Verify CSS is not hiding the buttons.
Images Squeezed or Overflowing: Ensure the Thumbnail Height is set appropriately. Check that images are not too large. Clear browser cache and Joomla cache. Verify responsive CSS is loading correctly.
Module Not Visible on Page: If you are using Firefox or Google Chrome, right-click on your website and click on "View Page Source". In the source code, search for text like "jxScroller" or "thumbnail-scroller". If you don't find the text, then it's confirmed that the module isn't activated on the page. Check module assignment and menu item selection.
Changes Not Reflecting: If Joomla cache is activated, try to clear it once after you make changes to the module parameter settings. Go to System > Clear Cache. Also clear your browser cache.
JavaScript Errors: Check browser console (F12) for JavaScript errors. Ensure jQuery is loaded properly. Verify that all asset files are accessible (check file permissions).
Horizontal Scroll on Mobile: The scroller should prevent horizontal page scrolling. If you see horizontal scroll, check that the module width is set correctly (use percentage for responsive layouts). Verify responsive CSS is loading.
Adding Module Inside Article: To add this module inside an article, go through the URL: https://docs.joomla.org/How_do_you_put_a_module_inside_an_article?