Easy Image Overlay

Introduction

Easy Image Overlay is a powerful Joomla system plugin that allows you to add beautiful, customizable text and icon overlays to your images using simple shortcodes. With complete style control, clickable links, and Font Awesome icon support, this plugin makes it easy to create engaging visual content for galleries, portfolios, and product showcases.

Key Highlights:

• Full Joomla 4, 5 & 6 Compatibility
• Customizable Text and Icon Overlays
• Clickable Image Links
• Font Awesome Icon Integration
• Shortcode Examples Tab with One-Click Copy
• Performance Optimized - Assets Only Load When Needed
• Enhanced Security with Comprehensive Input Sanitization

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 in 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: EasyImageOverlay_UNZIP.zip

Unzipping the Package

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

• plg_system_imageoverlay_X.x.zip: This is the installation file compatible with Joomla 4.x, 5.x, and 6.x.
• 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: Navigate to Extensions > Manage > Install, then click on the "Upload Package File" tab. Click "Browse" to select the appropriate installation file (plg_system_imageoverlay_X.x.zip), then click "Upload and Install."

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

Enabling the Plugin

After installation, navigate to Extensions > Plugins, search for "System - Easy Image Overlay", and click on it to enable and configure the plugin.

General Settings

Access the plugin settings by navigating to Extensions > Plugins, and find System - Easy Image Overlay in the list.

General Settings

• Link Target Behavior: Choose how links should open when users click on images (default is New Tab).
  • New Tab: Opens links in a new browser tab (recommended for external links)
  • Same Page: Opens links in the current window (recommended for internal navigation)
• Load Font Awesome Icons: Enable this option to load Font Awesome icon library (default is Yes).
  • Set to No if your template or another extension already loads Font Awesome to avoid duplicate loading
  • Font Awesome is required if you plan to use icons in your image overlays
• Custom CSS Styles: Add your custom CSS code here to further customize the appearance of image overlays.
  • This CSS will be added to the page head section
  • Example: .eImageoverlay { margin: 10px; }
  • You can target overlay elements using CSS selectors like .eImageoverlay, .easyImageoverlay, .imgOverlay

Shortcode Usage

Shortcode Examples Tab

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

Basic Syntax

Here is the syntax to integrate image overlays into your content. Write the code in your article where you want to show the image overlay.

Basic Image with Overlay Text

{imageoverlay image="images/sample.jpg" overlaytext="Click to View"}{/imageoverlay}

Image with Icon and Overlay

{imageoverlay image="images/sample.jpg" overlaytext="View Details" icon="fa-search"}{/imageoverlay}

Image with Link

{imageoverlay image="images/sample.jpg" url="https://example.com" overlaytext="Visit Site" icon="fa-external-link"}{/imageoverlay}

Image with Custom Colors

{imageoverlay image="images/sample.jpg" overlaytext="Read More" overlaybgcolor="#000000" overlaytextcolor="#ffffff"}{/imageoverlay}

Image with Custom Size

{imageoverlay image="images/sample.jpg" imgwidth="500px" imgheight="300px" overlaytext="Custom Size"}{/imageoverlay}

Available Parameters

• image: Path to the image file (required)
• overlaytext: Text to display in the overlay
• icon: Font Awesome icon class (e.g., fa-search, fa-play)
• url: Link URL when image is clicked
• overlaybgcolor: Overlay background color (hex or rgb)
• overlaytextcolor: Overlay text color (hex or rgb)
• overlayopacity: Overlay opacity (0.0 to 1.0)
• overlayfontsize: Font size for overlay text (e.g., 16px, 1.2em)
• overlaypadding: Padding for overlay content
• overlay: Set to true for always-visible overlay
• imgwidth: Image width (e.g., 500px, 100%)
• imgheight: Image height (e.g., 300px, auto)
• alt: Alt text for the image
• class: Custom CSS class

Where to Use

You can add image overlay shortcodes in:

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

Features

Core Features

• Image Overlays with Text & Icons: Add customizable text overlays and Font Awesome icons to any image for enhanced visual appeal.
• Complete Style Customization: Full control over overlay colors, opacity, font size, padding, and image dimensions.
• Clickable Image Links: Make images clickable with support for internal links, external URLs, and custom link targets.
• Font Awesome Icon Support: Built-in Font Awesome icon library integration with option to disable if already loaded.
• Shortcode Examples Tab: Built-in tab with 12 ready-to-use shortcode examples and one-click copy functionality.
• Performance Optimized: Assets only load when image overlay shortcodes are detected on the page.

Advanced Features

• Enhanced Security: Comprehensive input sanitization for image paths, URLs, colors, sizes, and text content.
• Path Traversal Protection: Advanced image path validation prevents directory traversal attacks.
• Smart Tag Detection: Early tag detection ensures assets load before head compilation for optimal performance.
• Custom CSS Support: Add custom CSS code directly in plugin settings for advanced styling.
• Hover or Always Visible: Choose between hover-activated overlays or always-visible overlays.
• Responsive Design: Works perfectly on all devices including mobile phones and tablets.

Compatibility

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

FAQ

• How do I add an image overlay to my content?

  • Use the shortcode syntax: {imageoverlay image="path/to/image.jpg" overlaytext="Your Text"}{/imageoverlay}. You can find ready-to-use examples in the Shortcode Examples tab in plugin settings.

• Can I customize the overlay colors?

  • Yes! Use the overlaybgcolor and overlaytextcolor parameters in your shortcode. Example: {imageoverlay image="image.jpg" overlaytext="Text" overlaybgcolor="#000000" overlaytextcolor="#ffffff"}{/imageoverlay}

• How do I add Font Awesome icons to overlays?

  • Use the icon parameter with a Font Awesome icon class. Example: {imageoverlay image="image.jpg" icon="fa-search" overlaytext="Search"}{/imageoverlay}. Ensure Font Awesome is enabled in plugin settings.

• Can I make images clickable?

  • Yes! Use the url parameter to add a link. Example: {imageoverlay image="image.jpg" url="https://example.com" overlaytext="Visit Site"}{/imageoverlay}. Configure link target behavior in plugin settings.

• How do I set custom image dimensions?

  • Use the imgwidth and imgheight parameters. Example: {imageoverlay image="image.jpg" imgwidth="500px" imgheight="300px" overlaytext="Text"}{/imageoverlay}

• Can I make the overlay always visible instead of hover-only?

  • Yes! Add overlay="true" to your shortcode. Example: {imageoverlay image="image.jpg" overlaytext="Always Visible" overlay="true"}{/imageoverlay}

• Which Joomla versions are supported?

  • The plugin is fully compatible with Joomla 4.x, 5.x, and 6.x. It uses WebAssetManager for Joomla 5+ with automatic fallback for Joomla 4.

• Where can I find shortcode examples?

  • The plugin includes a built-in Shortcode Examples tab in the plugin configuration with 12 examples. Simply click "Copy" to copy any example to your clipboard.

• Do image overlays work on mobile devices?

  • Yes! The plugin is fully responsive and works perfectly on all devices including mobile phones and tablets. Overlays automatically adapt to different screen sizes.

• Why aren't my images showing?

  • Ensure the image path is correct and the image file exists. Use relative paths from your Joomla root (e.g., images/articles/image.jpg). Check that the plugin is enabled and that your shortcode syntax is correct.

Troubleshooting

Common Issues and Solutions

• Image Overlays Not Displaying

  • Ensure the plugin is enabled in Extensions > Plugins
  • Verify the shortcode syntax is correct: {imageoverlay image="..." overlaytext="..."}{/imageoverlay}
  • Check that the image path is correct and the image file exists
  • Ensure you have either overlaytext or icon parameter (overlays require at least one)
  • Clear Joomla cache and browser cache
  • Check browser console for JavaScript errors

• Images Not Loading

  • Verify the image path is correct (use relative paths from Joomla root)
  • Check file permissions on the image file
  • Ensure the image file exists in the specified location
  • Use paths like images/articles/image.jpg instead of absolute URLs

• Overlay Colors Not Applying

  • Check that color values are in correct format (hex: #000000 or rgb: rgb(0,0,0))
  • Verify the shortcode parameters are spelled correctly
  • Clear browser cache to see updated styles
  • Check if your template's CSS is overriding overlay styles

• Font Awesome Icons Not Showing

  • Ensure Load Font Awesome Icons is set to Yes in plugin settings
  • Check that the icon class is correct (e.g., fa-search, not fas fa-search)
  • If your template already loads Font Awesome, ensure it's compatible
  • Check browser console for CSS loading errors

• Links Not Working

  • Verify the url parameter is correctly formatted
  • Check that the URL is valid (test it directly in browser)
  • Ensure the link target behavior is configured correctly in plugin settings
  • Check browser console for JavaScript errors

• Plugin Assets Not Loading

  • The plugin only loads assets when image overlay shortcodes are detected on the page
  • Ensure your content contains valid {imageoverlay} shortcodes
  • For Joomla 5+, the plugin uses WebAssetManager - ensure you're using a compatible Joomla version
  • Check file permissions on the plugin's assets folder
  • Verify jQuery is loaded (included with Joomla by default)

• Shortcode Examples Tab Not Showing

  • Ensure the fields folder is properly installed in the plugin directory
  • Check that fields/shortcodes.php file exists
  • Clear Joomla cache and refresh the plugin configuration page
  • Verify the XML manifest includes the fields folder

Getting Help

If you continue to experience issues:

• Check Joomla error logs for PHP errors
• Verify you're using the latest version of the plugin
• Visit our support forum: https://support.joomlax.com
• Ensure all plugin files are properly installed and have correct permissions