Mx Swiper3

1. Requirements

• Joomla with the core Articles component (com_content) enabled when using the Articles source.
• A published module assigned to a template position and menu items.
• Joomla 4 or newer uses the modern content model; older supported Joomla installations use the legacy model.
• For article image resizing, the Joomla cache directory must be writable.
• For Folder mode, media must be inside the Joomla images directory.

2. Installation

1. In Joomla administrator, open System > Install > Extensions.
2. Upload the Mx Swiper3 ZIP package.
3. Open Extensions > Modules and create or edit Mx Swiper3.
4. Set the module to Published, choose a template position, and configure Menu Assignment.
5. Save the module and check the assigned front-end page.

Keep the module's assets, core, field, and tmpl folders. They contain the Swiper libraries, image helpers, custom form fields, and style layouts.

3. Quick Start

1. Choose a Style in General Settings.
2. Choose a Source: Articles, Custom Items, or Folder.
3. Configure the fields shown for that source.
4. Set the slider effect, height, responsive item counts, navigation, and pagination.
5. Publish the module in a visible template position.

For the first test, use Articles, select one published category, leave the default image order, enable pagination and arrows, and use the default Slide effect.

4. How the Module Works

1. Source selection: the get_source setting selects the data path.
2. Data preparation: Joomla articles are queried, Custom Items are read from the subform, or Folder mode scans the selected directory.
3. Layout selection: the selected value of get_style loads the matching file from tmpl.
4. Asset loading: Swiper JavaScript and CSS are loaded for the module. Fancybox assets are loaded only when Fancybox is enabled; jQuery is loaded only when requested.
5. Swiper initialization: assets/swiper/functions.js reads the generated Swiper options, including effect, loop, autoplay, breakpoints, navigation, pagination, and mouse-wheel settings.
6. Slide rendering: each item becomes a Swiper slide containing media, optional text, and an optional link or lightbox control.

The module caches the prepared list through Joomla's module cache. Clear the Joomla cache after changing source files, folder contents, or settings if the front end still shows an older result.

5. General Settings

Style

Loads one of the available presentation templates: Default or Style 1 through Style 19. The style controls the slide composition and visual treatment; not every style uses every Swiper option in the same way.

Fancybox

When enabled, adds a fullscreen button to supported media and opens the current image, MP4, YouTube, or Vimeo item in a Fancybox gallery. It is available for the styles listed by the field's conditional rule and is disabled by default.

Layer images

Available for Style 1. Adds the style's decorative background layers above and below the slide content.

Slider height

Sets the height used by the slider, from 100vh to fixed values between 500px and 1000px.

Version

Selects the light or dark visual variation. The light option loads the module's light stylesheet.

Layer Background

Enables the semi-transparent overlay used by styles that support the dark slide layer. This can improve text contrast over photographs.

6. Swiper Controls

Slider Effect

Choose the transition effect supported by the selected style:

• Fade, Slide, Coverflow, Flip, Cube, Creative, Cards
• Gel is available as gl for the default and Style 14 settings.

Centered Slides and Loop

Centered Slides centers the active slide. Loop continuously cycles from the last slide back to the first.

Auto play and Delay time

Enable Auto play to advance slides automatically. Delay time controls the pause between slides from 2 to 15 seconds. Autoplay is configured not to stop when a visitor interacts with the slider.

Animation speed and Space Between

Animation speed controls transition duration from 0.5 to 7 seconds. Space Between adds a gap between slides using the available values from 0 to 40.

Parallax effect

Enables the image parallax movement on supported styles. Parallax amount sets the movement percentage from 1% to 40%.

Mouse wheel

Allows visitors to change slides with the mouse wheel on styles that expose this setting. Style 15 uses its own mouse-wheel field.

Responsive item counts

For Slide, Coverflow, and Cards effects, configure the number of visible items independently for desktop, laptop, tablet, and mobile. Other effects generally display one slide at the largest breakpoint because their visual design requires a single active slide.

Pagination and arrows

Pagination displays clickable slide indicators and offers two styles. Arrows display previous/next controls and offer three styles. Both can be disabled independently.

Thumbnails

Styles 16 and 19 expose the Thumbs setting. It controls the number of thumbnail slides visible, from 2 to 8.

7. Data Sources

Articles

Articles mode uses Joomla's com_content Articles model. It returns published articles available to the current visitor and creates the article, category, and read-more links.

• Select Category: limits results to one or more categories.
• Child Category Articles: includes or excludes descendant categories.
• Category Depth: limits how many child-category levels are included.
• Tags: filters articles by selected Joomla tags.
• Featured Articles: show all eligible articles, hide featured articles, or show only featured articles.
• Article Field to Order By: manager order, featured order, hits, title, ID, alias, created/modified/publishing dates, or random.
• Ordering Direction: ascending or descending.
• Count: maximum number of articles. A value of 0 means all articles.
• Open Link: same window, new window, or a popup window.
• Custom Fields: triggers Joomla content plugin events for the article.

Article Display

• Category Title: shows the category name and category link.
• Item Title: shows the article title.
• Title Maxlength: truncates the title by character count; 0 keeps the full title.
• Description display: shows the cleaned article intro text.
• Description Maxlength: truncates the intro text; 0 keeps all text.
• Author display: shows the article author.
• Date display: shows the created date.
• Date Format: controls the Joomla/PHP date format, such as d M Y or Y-m-d.
• Show Read More and Read More Text: control the article link button.

Article Images

The helper searches enabled image sources in the order entered in Order to Get. The first available image is used by the article styles.

• image_intro: the Joomla Images and Links intro image.
• image_fulltext: the Joomla full-text image.
• inline_introtext: images found in the intro HTML.
• inline_fulltext: images found in the full-text HTML.
• external: external or generated image paths supported by the helper.

Enable or disable each source with the corresponding From Image... field. If no image is found, the module uses modules/mod_mx_swiper3/assets/images/noimage.jpg or the configured placeholder path.

Image resizing

Resize Mode supports None, Center, Fill, Fit, and Stretch. When resizing is enabled, set compression quality from 1 to 100, output format (GIF, JPEG, PNG, or WEBP), transparency behavior, width, and height. Generated images are stored through the module's image helper and cache.

Custom Items

Custom Items are entered directly in the repeatable Items(s) field. Add one item for each slide, then drag or arrange the entries in the desired order.

Custom Items do not use article categories, article metadata, or article image extraction. Their media and text come entirely from the subform values.

Folder

Folder mode reads media from the selected directory under Joomla's images folder, including nested subfolders. The Folder field is populated by the module's custom foldertree field.

• Supported file types: jpg, jpeg, png, gif, webp, bmp, and mp4.
• Images become image slides; MP4 files become looping, muted video slides.
• Files are sorted naturally by their relative path.
• The filename before the first pipe is used as the title; a leading number followed by a separator is removed from the displayed title.
• Text after the first pipe is used as the description.
• Hyphens and underscores in both title and description are displayed as spaces.

Example filename:

01 - Our-services | Fast, reliable support.jpg

This produces the title Our services and the description Fast, reliable support; the leading 01 - is hidden. Set Count to limit the number of scanned items; use 0 for all matching files.

8. Styles

The package includes 20 selectable layouts: Default and Style 1 through Style 19. Each layout is implemented in its own file in tmpl and shares the same source types and core media model, while arranging captions, overlays, controls, and thumbnails differently.

• Default: general-purpose Swiper presentation with the extended effect options.
• Style 1: supports the optional Layer images setting.
• Styles 2-13: alternate content and overlay compositions using the standard Swiper effects.
• Style 14: uses the extended effect selector, including Gel.
• Style 15: has its own mouse-wheel option.
• Styles 16 and 19: support the Thumbs count control.
• Style 17: uses the module's full-height slider treatment and thumbnail-related markup.
• Style 18: supports Fancybox and the standard overlay controls.

The exact combination of conditional fields is controlled by mod_mx_swiper3.xml. If a setting is hidden after changing Style, that is intentional: the selected layout does not expose that option.

9. Custom CSS and Advanced Settings

• CSS code: add safe HTML-filtered CSS declarations for this module instance. Scope selectors to the module classes where possible.
• Module Class Suffix: adds a class suffix to the module wrapper for template-specific styling.
• Alternative Layout: selects a Joomla module layout override when one is available.
• Caching: uses Joomla's global module-cache setting or disables caching for the module.
• Cache Time: controls the cache duration when the module cache setting uses a custom time.
• Load jquery: loads the bundled jQuery 3.6.0 file. Leave this disabled when the template already loads a compatible jQuery instance.

10. Troubleshooting

No slides appear

• Confirm the module is published, assigned to the current menu item, and placed in a rendered template position.
• For Articles, confirm articles are published, accessible, assigned to the selected category, and allowed by language/tag/featured filters.
• For Custom Items, confirm at least one entry is published.
• For Folder mode, select a folder below images and check the file extension.

Images are missing

• Check the article image source switches and Order to Get.
• Check that the Custom Item media field matches its selected Type.
• Check the placeholder path and cache permissions.

Folder titles or descriptions are empty

Use the filename convention Title | Description.extension. The pipe character separates title and description; folders are scanned recursively but only supported extensions are included.

Video does not play

MP4 items use autoplay, muted, and loop attributes. Check that the URL is reachable, the file is a valid MP4, and the server sends a video MIME type. YouTube and Vimeo items require the video ID, not the full watch URL.

Slider height or effects look wrong

Check the selected Style, Slider height, effect compatibility, and whether another template stylesheet overrides the module's Swiper classes. Clear Joomla and browser caches after CSS changes.

JavaScript conflicts

Disable Load jquery when jQuery is already loaded by the template. Also check that another extension is not loading a conflicting Swiper version or duplicate Fancybox assets.

11. Updating

Back up the module configuration and site files before updating. Install the newer package through Joomla's extension installer. The XML manifest declares an update server, so Joomla can offer updates when that server is reachable. After updating, verify the selected Style, source data, and custom CSS.