# Image Hotspots Field for ACF Capture coordinates relative to an image for creating interactive image maps with clickable hotspots. **Now with full Gutenberg block editor support!** --- ## Description This plugin adds a custom ACF field type that allows users to click on an image and capture X/Y coordinates. Perfect for creating interactive image maps, product hotspots, or any feature requiring precise coordinate-based positioning. **This is a fork of the original ACF Image Hotspots Field by Andrew Rockwell**, enhanced with full support for ACF blocks in the Gutenberg editor. ### Key Features - Click on an image to capture precise X/Y coordinates - Supports both pixel-based and percentage-based coordinates - Links to existing ACF image fields - Visual marker shows the selected position - Works in regular ACF field groups AND ACF blocks - **NEW:** Full Gutenberg block editor compatibility - Compatible with ACF 5.8+ ### What's New in This Fork This fork adds critical improvements for modern WordPress development: - **✅ Gutenberg Block Support:** Works seamlessly in ACF blocks within the Gutenberg editor - **✅ Event Capture Fix:** Solves the issue where Gutenberg intercepts click events - **✅ Improved DOM Search:** Enhanced field discovery in complex block structures - **✅ Enhanced Visibility:** Fixed z-index and marker visibility in block contexts - **✅ Auto-Refresh:** Automatically updates block previews when coordinates change ### Original Plugin Original plugin by **Andrew Rockwell** - Thank you for creating this excellent field type! This fork maintains 100% backwards compatibility with the original while adding modern editor support. --- ## Compatibility This ACF field type is compatible with: - ACF 5.8+ - WordPress 5.8+ - Gutenberg block editor - Classic editor - PHP 7.2+ --- ## Installation ### From GitHub/GitLab 1. Download or clone this repository 2. Copy the `acf-image-mapping-hotspots` folder into your `wp-content/plugins` folder 3. Activate the plugin via the WordPress plugins admin page 4. Create a new field via ACF and select the "Image Mapping" type ### From WordPress.org (Coming Soon) 1. Go to Plugins > Add New 2. Search for "ACF Image Mapping Hotspots" 3. Click "Install Now" and then "Activate" --- ## Usage ### Field Setup 1. Create or edit an ACF field group 2. Add a new field and select "Image Mapping" as the field type 3. In the field settings, enter the **Image Field Label** - this should match the field name of an existing ACF image field in the same group 4. Optionally enable "Percentage Based Coordinates" to store coordinates as percentages instead of pixels ### In ACF Field Groups The field will automatically find the linked image field and display it. Click on the image to set the hotspot coordinates. ### In ACF Blocks Works identically to regular field groups! The Gutenberg fix ensures clicks are captured correctly in the block editor. ### Retrieving Coordinates ```php // Get the coordinates $coords = get_field('hotspot_field_name'); // Returns: "150px,200px" or "45.5%,60.2%" depending on settings // Parse coordinates list($x, $y) = explode(',', $coords); ``` ### Example: Product Hotspot ```php
``` --- ## Technical Details ### Gutenberg Block Support This fork includes a sophisticated event capture system that intercepts mouse events before Gutenberg's React event system can prevent them. This ensures reliable coordinate capture in all contexts. For detailed technical information about the Gutenberg fixes, see [GUTENBERG_FIX.md](GUTENBERG_FIX.md). ### Field Structure * `/assets`: Asset files (CSS, JS, images) * `/fields`: Field class files * `acf-image_hotspots-v5.php`: ACF 5+ compatible field class * `/lang`: Translation files * `acf-image-hotspots.php`: Main plugin file --- ## Frequently Asked Questions ### Does this work with ACF blocks in Gutenberg? Yes! This is the primary enhancement in this fork. The original plugin didn't work in ACF blocks due to event interception issues, which have been completely resolved. ### Can I use percentage-based coordinates? Yes, enable the "Percentage Based Coordinates" option in the field settings. This is useful for responsive designs where the image size may vary. ### Does this work with repeater fields? Yes, the field automatically searches through repeater parent fields to find the linked image. ### Is this backwards compatible with the original plugin? Yes, 100%. You can safely switch from the original plugin to this fork without any breaking changes. --- ## Changelog ### 0.2 (2025-12-05) * Updated plugin branding to Levels Branding and Development * Updated plugin name to "Image Hotspots Field for ACF" for WordPress.org consistency * Minor documentation updates ### 0.1 (2025-01-29) * Fork created with Gutenberg support * Added event capture phase interception for ACF blocks * Improved DOM search for block contexts * Added CSS fixes for z-index and visibility * Added automatic block preview refresh on coordinate change * Enhanced documentation with debugging guides * 100% backwards compatible with original plugin ### 0.0.1 (Original by Andrew Rockwell) * Initial release of ACF Image Hotspots Field --- ## Credits **Original Plugin:** Andrew Rockwell **Gutenberg Fork:** Levels Branding and Development **Website:** https://levels.dev/ --- ## Support For issues specific to this plugin: - GitLab Issues: https://gitlab.com/levels-dev/plugins/advanced-custom-fields-image-hotspots-field-fork For general ACF questions: - ACF Documentation: https://www.advancedcustomfields.com/resources/ --- ## Other Plugins by Levels Check out our other WordPress plugins: - [Ready-Made Oxygen Integration](https://wordpress.org/plugins/ready-made-oxygen-integration/) - Seamless integration for Oxygen Builder with pre-built components and utilities Visit [levels.dev/plugins](https://levels.dev/plugins) for more tools and resources. --- ## License GPLv2 or later http://www.gnu.org/licenses/gpl-2.0.html