=== Random Image Block for Block Editor ===
Contributors:      mhimon, ultradevs
Tags:              random image, image rotator, gutenberg block, dynamic image, lightbox
Requires at least: 5.8
Tested up to:      7.1
Stable tag:        1.2.0
Requires PHP:      7.0
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Display dynamic, randomized images, background banners, and interactive image rotators in WordPress Block Editor (Gutenberg).

== Description ==

**Random Image Block for Block Editor** is a lightweight, high-performance Gutenberg block that lets you effortlessly display random images from your WordPress media library. Perfect for hero banners, rotating header backgrounds, dynamic portfolio showcases, sponsor logos, daily featured photos, and interactive image galleries.

Keep your website fresh and engaging on every page load or automatically rotate images at custom time intervals with smooth shuffle animations, interactive hover effects, advanced lightbox modals, and responsive layout controls.

[Live Demo & Documentation](https://ultradevs.com/) | [Upgrade to Pro](https://ultradevs.com/) | [Support & Contact](https://ultradevs.com/contact-us/)

---

### 🌟 Why Choose Random Image Block?

* **Boost Visitor Engagement**: Dynamic content keeps your landing pages, blog posts, and sidebar widgets feeling lively and modern.
* **SEO & Performance Optimized**: Built with lightweight Vanilla JavaScript and optimized CSS. Supports native and progressive lazy loading for fast Core Web Vitals.
* **No Coding Required**: Intuitive Gutenberg sidebar controls allow you to configure layouts, filters, animations, and conditions in seconds.
* **Responsive by Default**: Granular controls for Desktop, Tablet, and Mobile devices ensure pixel-perfect presentation on every screen size.

---

### 🆓 Free Version Features

* **Media Library Integration**: Pick any collection of images directly from your WordPress media library.
* **Responsive Image Alignment**: Align images to the left, center, right, or full width.
* **Custom Link Options**: Link images to their WordPress attachment page, a custom URL, or open in a new tab.
* **Live Sidebar Previews**: Preview and manage your selected gallery images directly inside the block inspector.
* **Clean & Semantic Markup**: Output clean HTML with standard WordPress block styling and accessibility attributes.

---

### 🚀 Pro Version Features & Highlights

Upgrade to **Random Image Block Pro** to unlock powerful display modes, animations, and enterprise-grade personalization tools:

#### 1. 🔍 Advanced Lightbox Modal
* **Full-Featured Popup**: Open images in a distraction-free, responsive lightbox overlay.
* **Zoom & Fullscreen**: Built-in 2x zoom toggle and native browser fullscreen mode.
* **Captions & Navigation**: Display image captions with next/previous navigation and keyboard arrow/Escape support.

#### 2. 🖼️ Image Background Mode
* **Section & Hero Backgrounds**: Transform any random image into a full-width background container.
* **Color Overlay & Opacity**: Customize overlay colors and alpha transparency for optimal text readability.
* **Parallax Depth Effect**: Optional smooth parallax scrolling background for modern hero banners.

#### 3. 🔄 Shuffle Animations & Auto-Refresh
* **Seamless Transitions**: Choose from smooth **Fade**, **Slide**, or **Zoom** shuffle transitions.
* **Custom Transition Duration**: Fine-tune animation speed from 100ms to 2000ms.
* **Auto-Rotate Timer**: Automatically cycle through random images every X seconds without requiring a page reload.

#### 4. 🎯 Smart Conditional Display
* **User Role Targeting**: Display specific images exclusively to logged-in users, logged-out guests, or specific WordPress roles (e.g. Administrator, Editor, Subscriber).
* **Time-Based Scheduling**: Show different images during day, evening, or custom operating hours (e.g. 09:00 to 18:00).
* **Seasonal Personalization**: Automatically switch image pools for Spring, Summer, Autumn, or Winter.
* **Date Range Campaigns**: Set start and expiration dates for limited-time promotions, holiday campaigns, or flash sales.

#### 5. ⚖️ Weighted Random & Exclusion Controls
* **Priority Probability (Weighting)**: Assign custom weights to individual images so key products or banners appear more frequently.
* **Image Exclusion**: Temporarily hide or exclude specific images from the random pool without deleting them.

#### 6. ✨ Interactive Image Hover Effects
* **Engaging Micro-Animations**: Choose from Zoom In, Zoom Out, Pan, Rotate, Grayscale-to-Color Reveal, and Opacity change on mouse hover.
* **Hardware-Accelerated CSS**: Ultra-smooth 60fps performance without sluggish JavaScript recalculations.

#### 7. 🎨 Live CSS Image Filters
* **Real-Time Styling**: Apply Grayscale, Blur, Brightness, Contrast, Saturation, and Hue-Rotate directly from the block editor.
* **One-Click Reset**: Easily reset individual filters to default values.

#### 8. 📝 Advanced Caption Styling & Positioning
* **Overlay or Below**: Place captions underneath the image or overlay them directly on top with custom X/Y focal point coordinates.
* **Hover-Only Captions**: Reveal captions smoothly when users hover over the image.
* **Typography & Styling**: Control caption background color, opacity, text color, font size, border radius, and responsive padding.

#### 9. 📐 Device-Specific Sizing & Shapes
* **Responsive Width & Height**: Set separate width, height, and unit metrics (px, %, vh, rem) for Desktop, Tablet, and Mobile.
* **Object-Fit Control**: Choose between `cover`, `contain`, `fill`, or `scale-down` to prevent image stretching.
* **Rounded Corners & Circle Shape**: Customize border radius per corner or create 100% circular profile avatars and badges.

#### 10. ⚡ Smart Caching & Sticky Mode
* **Sticky Mode (Session Persistence)**: Maintain the same randomly selected image for a user across multiple page visits using local storage.
* **Mobile bfcache Compatibility**: Ensures reliable image randomization on mobile browsers and Back/Forward cache restores.
* **Lazy Loading**: Progressive image loading with smooth fade-in to boost Google PageSpeed and Core Web Vitals scores.

---

### 💡 Common Use Cases

* **E-Commerce & WooCommerce**: Display random promotional banners, seasonal sale graphics, or daily featured products.
* **Portfolios & Photography**: Show rotating artwork, photography highlights, or design client showcases.
* **Testimonials & Quotes**: Pair inspirational quotes with alternating author headshots or background graphics.
* **Sponsors & Partner Logos**: Rotate verified sponsor logos and partner badges fairly on every visit.
* **Blogging & Editorial**: Keep header hero images fresh and varied for returning readers.

---

### 🤝 Join Our Community

* [Facebook Community](https://web.facebook.com/groups/powerfulblocks/)
* [Facebook Page](https://web.facebook.com/hello.ultradevs)
* [YouTube Channel](https://www.youtube.com/channel/UCc2yL-QGQjscXpPx9Pp7J8w)
* [Twitter / X](https://twitter.com/ultraDevsBD)
* [LinkedIn](https://www.linkedin.com/company/ultradevs/)
* [GitHub](https://github.com/ultraDevs)

== Installation ==

1. Log in to your WordPress admin dashboard.
2. Navigate to **Plugins > Add New**.
3. Search for **Random Image Block**.
4. Click **Install Now** and then **Activate**.
5. Open any page or post in the Block Editor (Gutenberg) and click the **+** icon to insert the **Random Image Block**.
6. Select multiple images from your Media Library and customize your settings in the sidebar panel.

== Frequently Asked Questions ==

= Does Random Image Block work with any WordPress theme? =
Yes! Random Image Block is built following official WordPress block API standards and works seamlessly with Classic, Block-based (FSE), and Hybrid themes.

= Can I link each random image to a different URL? =
Yes. You can link images to their WordPress attachment page, a single custom URL, or enable the interactive Lightbox modal.

= How does Auto-Refresh work? =
When auto-refresh is enabled, the block automatically switches images at your chosen interval (in seconds) using smooth fade, slide, or zoom animations without reloading the page.

= Does it affect website performance or Core Web Vitals? =
No. The plugin uses lightweight vanilla JavaScript with no heavy external dependencies (like jQuery). It also includes built-in Lazy Loading for fast page load times.

= Can I control how often certain images appear? =
Yes! In the Pro version, you can assign custom probability weights to each image so your most important banners or products appear more frequently.

== Changelog ==

= 1.2.0 - 08 Oct 2026 =
* Added: Full-featured Lightbox Modal with Zoom, Fullscreen, Caption, and Keyboard navigation.
* Added: Image Background Mode with overlay color, opacity, and parallax effects.
* Added: Image Hover Effects (Zoom, Pan, Rotate, Grayscale-to-color, Opacity).
* Added: Image Border Radius and circular shape option.
* Added: Lazy Loading support with smooth fade-in transitions.
* Added: Weighted Random selection and per-image exclusion controls.
* Added: Advanced Caption Styling (background color & opacity, typography, responsive padding, border radius).
* Added: Conditional Display options (User role, time of day, season, and date range).
* Update: Updated Freemius SDK to the latest version.

= 1.1.1 - 06 Oct 2026 =
* Fixed: Editor inspector controls layout overflow and panel clipping.
* Fixed: Mobile browser caching and back-forward cache (bfcache) image randomization on reload.
* Improved: Responsive width and height input controls in the block sidebar.

= 1.1.0 - 14 Feb 2026 =
* Added: Image Shuffle Animations (Fade, Slide, Zoom).
* Added: Auto-refresh Interval functionality.
* Added: Sticky Mode (Random Seed persistence via local storage).
* Added: Image Filters (Grayscale, Blur, Brightness, Contrast, Saturation, Hue Rotate).
* Added: Link Options (Attachment page, Custom URL).

= 1.0.5 - 18 Jan 2025 =
* Updated: Freemius SDK
* Updated: Deprecated Gutenberg Controls.
* New: Link Settings.

= 1.0.4 - 18 Jan 2025 =
* Updated: Freemius SDK
* Added: Translation Support

= 1.0.3 - 22 Nov 2023 =
* Added: Caption Over Image (Pro Version)
* Added: Some Core Controls

= 1.0.2 - 06 Nov 2023 =
* Some Fixes
* Added Menu Page
* Code Optimized

= 1.0.1 - 29 Oct 2023 =
* Added Block Controls
* Added Pro Version

= 1.0.0 - 6 June 2023 =
* Initial Release
