Welcome to the JR Image Optimizer! This guide will help you install, configure, and get the most out of your new image optimization suite for Joomla 5.

1. Installation

Installation is standard and follows the typical Joomla extension process.

  1. Download the package file (pkg_jrimageoptimizer_vX.X.X.zip).
  2. Log in to your Joomla Administrator panel.
  3. Navigate to System > Install > Extensions.
  4. Drag and drop the package file into the upload area (or click Browse to select it).
  5. Once the success message appears, the package is installed.

JR Image Optimizer Extensions

NOTE

The package installs both the System Plugin (which does the optimization) and the Administrator Module (which shows you the stats).

2. Getting Started

After installation, you need to enable the plugin to start optimizing your site.

  1. Go to System > Manage > Plugins.
  2. Search for "JR Image Optimizer".
  3. Click the status icon to Enable the plugin (System - JR Image Optimizer).

🚀 That's it! The plugin is now active with optimal default settings. You can immediately visit your frontend to see it in action.

3. Configuration Guide

To customize how the optimizer works, click on the plugin name (System - JR Image Optimizer) to open the settings.

Core Web Vitals (Performance)

These settings directly impact your Google PageSpeed scores.

  • LCP Optimization: (Default: Yes)
    • What it does: Automatically detects the Largest Contentful Paint (LCP) image (usually the main banner or hero image) and optimizes it for instant loading.
    • Recommendation: Keep this enabled for the best SEO boost.
  • Blur Placeholders (LQIP): (Default: Yes)
    • What it does: Displays a blurred, low-resolution version of the image while the high-quality version loads. This prevents the layout from "jumping" (Cumulative Layout Shift) and looks very professional.
  • Background Images: (Default: Yes)
    • What it does: Scans your CSS for background-image properties and converts them to use modern image-set(), serving WebP versions to supported browsers.

Image Settings

Control the quality and sizes of your generated images.

  • Responsive Breakpoints:
    • Description: A comma-separated list of widths (in pixels). The plugin creates a version of the image for each width.
    • Default: 240, 320, 480, 768, 1024, 1920 (Covers everything from small mobiles to 4K screens).
  • WebP Quality: (1-100, Default: 80)
    • Higher = Better looking, larger file.
    • Lower = More compression, smaller file.
    • 80 is a great balance for most sites.
  • Placeholder Quality: (1-20, Default: 10)
    • Controls how "blocky" or detailed the blur placeholder is. Lower is smaller and faster.

Exclusions

Sometimes you might want to skip optimization for specific images (e.g., a complex map or a specific banner).

  • Exclude Paths: Enter folder paths to ignore (e.g., /images/partners/).
  • Exclude CSS Classes: Enter class names. Any image with this class will be skipped.
    • Example: no-optimize, raw-image

4. Statistics Dashboard

The package includes a backend module that shows you how much space you've saved.

To view it:

  1. Go to your Admin Dashboard (Home Dashboard).
  2. If you don't see the JR Image Optimizer Stats widget, click Add Module usage and select it.
  3. It displays:
    • Total images processed.
    • Disk space saved.
    • Optimization percentage.

Statistics Dashboard

5. Troubleshooting / FAQ

Q: I don't see any changes on my site? A: Clear your Joomla Cache and Browser Cache. The plugin runs on the onAfterRender event, so cached pages might need to be refreshed.

Q: My images look blurry. A: Check your WebP Quality setting. If it's too low (below 60), try increasing it to 80 or 90.

Q: How do I know if it's working? A: Right-click an image on your site and select Inspect. You should see a <picture> tag or srcset attributes, and the source file should end in .webp.

For further support, please visit our Support Forum.