=== LONDOM - Out of Stock Alternatives ===
Contributors: londom
Tags: woocommerce, out of stock, alternatives, upsell, stock management
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Automatically show in-stock alternative products when items are out of stock. Smart recommendations prevent lost sales.

== Description ==

**Stop losing sales when products sell out.**  
LONDOM - Out of Stock Alternatives automatically replaces the Add to Cart button with smart product recommendations when an item is completely out of stock.

= Key Features =

* **Smart Recommendations** - Shows upsells first, then products from the same category
* **Variable Product Support** - Correctly handles products with multiple variations
* **Mobile-First Design** - Clean, responsive interface that works on all devices
* **Performance Optimized** - Intelligent caching system with soft-refresh validation
* **Multilingual Ready** - Compatible with Polylang and WPML
* **Cache Plugin Support** - Works with WP Rocket, W3TC, LiteSpeed, and WP Fastest Cache
* **Accessible** - Full ARIA support and keyboard navigation

= How It Works =

1. **Detection** - Automatically detects when a product (simple or variable) is completely out of stock
2. **Replacement** - Removes the Add to Cart button and shows an alternatives block
3. **Recommendations** - Displays 4 in-stock products: upsells first, then same-category items
4. **Smart Caching** - Validates cached products on each page load to ensure accuracy

= Perfect For =

* WooCommerce stores with frequent stock changes
* Fashion and apparel shops with seasonal inventory
* Electronics stores with limited stock items
* Any e-commerce site that wants to reduce lost sales from stockouts

= Developer Friendly =

Multiple filters and actions available for customization:

* `londom_alternatives_count` - Change number of alternatives shown
* `londom_alternatives_title` - Customize the heading text
* `londom_alternative_products_query_args` - Modify the query for finding alternatives
* `londom_should_replace_add_to_cart` - Control when replacement happens
* `londom_oos_display_hook` - Change the hook where the block is printed
* `londom_oos_display_priority` - Change the priority on that hook
* `londom_use_context_aware_cache` - Enable context-aware caching
* And many more...

= Requirements =

* WordPress 6.0 or higher
* WooCommerce 6.0 or higher
* PHP 8.0 or higher

= Support =

For support, please use the [WordPress.org support forum](https://wordpress.org/support/plugin/londom-out-of-stock-alternatives/).

== Installation ==

= Automatic Installation =

1. Log into your WordPress admin panel
2. Navigate to Plugins → Add New
3. Search for "LONDOM Out of Stock Alternatives"
4. Click "Install Now" and then "Activate"

= Manual Installation =

1. Download the plugin ZIP file
2. Log into your WordPress admin panel
3. Navigate to Plugins → Add New → Upload Plugin
4. Choose the ZIP file and click "Install Now"
5. Activate the plugin

= After Activation =

The plugin works automatically! Visit any out-of-stock product page to see the alternatives block in action.

**Optional Configuration:**

You can customize behavior using WordPress filters in your theme's `functions.php`:

`
// Change number of alternatives shown (default: 4)
add_filter( 'londom_alternatives_count', function() { 
    return 6; 
});

// Customize the heading text
add_filter( 'londom_alternatives_title', function() { 
    return 'You might also like these'; 
});

// Enable context-aware caching (for multilingual/multi-currency sites)
add_filter( 'londom_use_context_aware_cache', '__return_true' );

// Change where the block is printed (defaults: woocommerce_before_single_product, priority 20)
add_filter( 'londom_oos_display_hook', function() {
    return 'woocommerce_before_single_product';
});
add_filter( 'londom_oos_display_priority', function() {
    return 20;
});
`

== Frequently Asked Questions ==

= Why isn't the alternatives block showing? =

The plugin only displays alternatives when a product is **completely** out of stock:
* For simple products: stock must be 0 and backorders disabled
* For variable products: ALL variations must be out of stock or unavailable

Check your product's stock settings in WooCommerce.

= Can I change how many alternative products are shown? =

Yes! Use this filter in your theme's functions.php:

`add_filter( 'londom_alternatives_count', function() { return 6; });`

= How are alternative products selected? =

The plugin uses a smart two-step process:
1. **First priority:** Upsell products (that are in stock)
2. **Fallback:** Products from the most specific categories assigned to the product, ordered by sales performance

This ensures relevant recommendations every time.

= Is it compatible with my theme? =

Yes! The plugin uses standard WooCommerce hooks and includes mobile-first CSS that adapts to most themes. The styles are minimal and designed to blend with your existing design.

= Does it work with variable products? =

Absolutely! The plugin intelligently checks all variations. If even ONE variation is available (in stock or with backorders enabled), the normal Add to Cart remains visible.

= Will it slow down my site? =

No. The plugin includes an intelligent caching system that stores alternative product IDs and validates them on each page load. This "soft-refresh" approach keeps data accurate while maintaining performance.

= Is it compatible with caching plugins? =

Yes! Built-in compatibility with:
* WP Rocket
* W3 Total Cache
* LiteSpeed Cache
* WP Fastest Cache

The plugin automatically purges relevant cache when products are updated.

= Can I translate the plugin? =

Yes! The plugin is fully translation-ready:
* Text domain: `londom-out-of-stock-alternatives`
* Compatible with Polylang and WPML
* All user-facing strings are translatable

= How do I clear the plugin's cache? =

The cache clears automatically when:
* A product is updated
* Stock status changes
* Prices change
* Upsells are modified

For manual clearing, deactivate and reactivate the plugin.

= Can I customize the appearance? =

Yes! The plugin includes CSS classes you can target:
* `.londom-oos-wrap` - The wrapper around the notice and the alternatives
* `.londom-oos-banner` - The "out of stock" notice
* `.londom-oos-box` - The alternatives container
* `.londom-oos-grid` - The product grid
* `.londom-oos-item` - Individual product cards

Add custom CSS in Customizer → Additional CSS.

= Does it support HPOS (High-Performance Order Storage)? =

Yes! The plugin declares full compatibility with WooCommerce HPOS.

= Is there a PRO version? =

Not yet, but we're working on advanced features for a PRO version. The FREE version will always remain feature-complete for basic needs.

== Screenshots ==

1. Alternatives block shown at the top of an out-of-stock product page
2. Mobile view with responsive grid layout
3. Alternative products with prices and images

== Changelog ==

= 1.4.0 - 2026-09-26 =
* Fixed: The alternatives block is now printed above the product layout, fixing the broken columns with Blocksy and other flex/grid themes
* Added: `londom_oos_display_hook` and `londom_oos_display_priority` filters to change where the block is printed
* Removed: Forced dark color scheme in the block styles
* Fixed: PHP warning when a variation's stock changes
* Improved: Variations now also clear the cache of their parent product
* Fixed: WP Rocket is now purged only when the stock status changes, not while the block is printed
* Improved: Fallback alternatives now come only from the most specific categories of the product
* Improved: Previously cached alternatives are invalidated once after the update
* Changed: All texts are now in English and can be translated on translate.wordpress.org

= 1.3.5 - 2026-02-10 =
* Fixed: Plugin file name aligned with WordPress.org slug
* Fixed: Text domain consistency across all files
* Improved: Full compliance with WordPress.org requirements
* Updated: Plugin URI and documentation links

= 1.3.4 - 2026-02-10 =
* Fixed: Text domain aligned with WordPress.org assigned slug
* Fixed: Plugin name formatting consistency across all files
* Updated: Minimum requirements - WordPress 6.0+ and PHP 8.0+
* Improved: Full compliance with WordPress.org plugin guidelines

= 1.3.2 - 2025-01-22 =
* Fixed: Text domain alignment with plugin slug for WordPress.org compliance
* Fixed: Replaced `_e()` with `esc_html_e()` for safe output
* Fixed: Added missing translators comments for sprintf placeholders
* Improved: Cache index system without direct SQL queries
* Improved: Enhanced code documentation and inline comments
* Improved: Better error handling for edge cases
* Tested: WordPress 6.9 compatibility
* Tested: WooCommerce 9.0 compatibility

= 1.3.1 - 2024-12-10 =
* Added: eBay-like placement at top of product page
* Added: Soft-refresh cache validation on page hits
* Added: Context-aware cache support (opt-in)
* Improved: Extended cache invalidation hooks
* Improved: Better variable product detection
* Fixed: Cache clearing on variation updates

= 1.3.0 - 2024-11-15 =
* Initial public release
* Feature: Automatic out-of-stock detection
* Feature: Smart alternatives via upsells → category fallback
* Feature: Mobile-first responsive design
* Feature: Accessible markup with ARIA labels
* Feature: Cache system with transients
* Feature: Multilingual support (Polylang/WPML)
* Feature: HPOS compatibility

== Upgrade Notice ==

= 1.4.0 =
The block is now printed outside div.product: check any custom CSS that targets it. Texts are now in English; on non-English sites they stay in English until the translation is available on translate.wordpress.org.

= 1.3.2 =
Important update for WordPress.org compliance. Aligns text domain with plugin slug and improves code quality. No breaking changes. Safe to update.

= 1.3.1 =
Improved cache system and better product placement. Recommended update for all users.

= 1.3.0 =
First stable release. Install and activate to start showing alternatives on out-of-stock products.

== Additional Information ==

= About LondomLab =

LondomLab creates practical WooCommerce tools that help online stores increase sales and improve customer experience. Visit [londomlab.com](https://londomlab.com) for more plugins and solutions.

= Privacy & Data =

This plugin does not:
* Collect any user data
* Use cookies or tracking
* Send data to external servers
* Store personal information

All data processing happens locally on your WordPress installation.

= Contributing =

Found a bug or have a feature request? Please report it on the [support forum](https://wordpress.org/support/plugin/londom-out-of-stock-alternatives/).

= Credits =

Developed with ❤️ by the LondomLab team.
