MWE EtchWP Enhancements

A WordPress plugin that enhances the Etch page builder with improved image handling and focus position support.

Features

🖼️ Automatic Image Enhancement

Automatically enhances images in Etch blocks with essential attributes:

• Responsive Images: Adds srcset attributes for different screen sizes
• Dimensions: Extracts width and height from filename or metadata
• Accessibility: Adds alt text from attachment metadata
• Decorative Images: Use alt="-" (hyphen) to mark images as decorative
• Performance: Generates sizes attributes for optimal image loading
• Smart Detection: Only adds missing attributes, never overwrites existing ones
• Optimized: Early-exit for images with complete attributes (minimal overhead)
• Efficient: Runtime cache prevents duplicate database queries

🎯 Focus Position Support

Integrates with focus point plugins to control image focal points:

• Applies CSS object-position based on focus point data
• Per-page overrides: Set custom focus points in Etch editor that override global Media Library values
• Visual editor: Click-to-set focus point UI in Etch's element settings panel
• Dynamic Data integration: Access focus points via {this.image.focusPoint} in Etch templates
• Compatible with:
  • Image Background Focus Position
  • Media Focus Point

Visual Focus Point Editor in Etch

The Focus Point Editor appears automatically when you select an image in the Etch canvas. It provides:

• Interactive Preview: Click anywhere on the image thumbnail to set the focus point
• Visual Marker: A crosshair marker shows the current focus position
• Position Display: Shows exact percentage values (e.g., "30.5% 45.2%")
• Override Indicator: Clearly shows whether you're using a page-specific override or the global Media Library value
• Reset Button: One click to remove the override and revert to the global focus point

Requirements

Required

• Etch page builder (v1.0.0 or higher recommended)
• PHP 8.1 or higher
• WordPress 5.9 or higher

Optional

For focus position features, install one of:

• Image Background Focus Position plugin
• Media Focus Point plugin

Installation

1. Ensure Etch page builder is installed and activated
2. Upload the mwe-etchwp-enhancements folder to /wp-content/plugins/
3. Activate the plugin through the WordPress 'Plugins' menu
4. (Optional) Install a focus position plugin for focal point features

Configuration

Disable Features via Filters

Add to your theme's functions.php:

// Disable image enhancement
add_filter( 'mwe_etchwp_enable_image_enhancement', '__return_false' );

// Disable focus position
add_filter( 'mwe_etchwp_enable_focus_position', '__return_false' );

Disable Features via Constants

Add to wp-config.php:

// Disable image enhancement
define( 'MWE_ETCHWP_IMAGE_ENHANCEMENT', false );

// Disable focus position
define( 'MWE_ETCHWP_FOCUS_POSITION', false );

How It Works

Image Enhancement Process

1. Hooks into render_block filter (priority 15) after Etch processes blocks
2. Detects <img> tags in supported Etch blocks
3. Performance check: Skips images that already have all attributes (early-exit)
4. Cache check: Returns cached attachment ID if image was previously processed
5. Attempts to find attachment ID from image URL using multiple strategies
6. Checks which attributes are missing
7. Adds only the missing attributes without modifying existing ones
8. Caches result: Stores attachment ID for future lookups within the same request

Supported Blocks

Full processing (image enhancement + focus position):

• etch/element - Standard HTML elements
• etch/dynamic-element - Dynamic HTML elements
• etch/raw-html - Raw HTML blocks
• etch/component - Component blocks

Focus position only:

• etch/dynamic-image - Dynamic Image element (Etch 1.0.0-beta-15+)

The Dynamic Image element in Etch already handles responsive image attributes (srcset, sizes, width, height) internally. This plugin only applies focus position styling to these images to avoid conflicts and duplicate processing.

In the Etch builder, selecting a Dynamic Image shows the focus point picker when a fixed WP Media ID is set. When the image source is dynamic (e.g. a loop expression), the focus point cannot target a single attachment, so a notice points you to the Media Library to set it per image instead.

Focus Position Process

1. Reads focus point data from compatible plugins
2. Adds data to attachment metadata via wp_get_attachment_metadata filter
3. Checks for per-page overrides stored in post meta
4. Applies CSS object-position during block rendering (override > global > default)
5. Automatically applies image enhancements as well (except for etch/dynamic-image)

Per-Page Focus Point Overrides

Focus points can be customized per-page in the Etch editor:

1. Select an image in the Etch canvas
2. Find the "Focus Point" section in Element Settings
3. Click on the preview image to set the focus point
4. The override is saved automatically for this page only
5. Click "Use Global" to remove the override and use the Media Library value

Priority order:

1. Per-page override (set in Etch editor)
2. Media Library focus point (global)
3. Default: 50% 50% (center)

Developer Documentation

Available Filters

mwe_etchwp_enable_image_enhancement

Control whether image enhancement is enabled.

/**
 * @param bool $enabled Default: true
 * @return bool
 */
apply_filters( 'mwe_etchwp_enable_image_enhancement', true );

mwe_etchwp_enable_focus_position

Control whether focus position feature is enabled.

/**
 * @param bool $enabled Default: true
 * @return bool
 */
apply_filters( 'mwe_etchwp_enable_focus_position', true );

mwe_etchwp_processable_blocks

Customize which Etch block types are processed for image enhancement and focus position.

/**
 * @param array $processable_blocks Default: ['etch/element', 'etch/dynamic-element', 'etch/raw-html', 'etch/component', 'etch/dynamic-image']
 * @return array
 */
apply_filters( 'mwe_etchwp_processable_blocks', $processable_blocks );

Example usage:

// Add a custom block type to processing
add_filter( 'mwe_etchwp_processable_blocks', function( $blocks ) {
    $blocks[] = 'etch/custom-block';
    return $blocks;
} );

// Remove a specific block from processing
add_filter( 'mwe_etchwp_processable_blocks', function( $blocks ) {
    return array_diff( $blocks, array( 'etch/raw-html' ) );
} );

mwe_etchwp_skip_responsive_blocks

Customize which blocks should skip responsive image processing (srcset, sizes, width, height). These blocks still receive focus position processing.

/**
 * @param array $skip_blocks Default: ['etch/dynamic-image']
 * @return array
 */
apply_filters( 'mwe_etchwp_skip_responsive_blocks', $skip_blocks );

Example usage:

// Add another block that handles its own responsive images
add_filter( 'mwe_etchwp_skip_responsive_blocks', function( $blocks ) {
    $blocks[] = 'etch/custom-responsive-block';
    return $blocks;
} );

mwe_etchwp_disable_auto_sizes

Restore the pre-1.2.12 behaviour of disabling WordPress core's sizes="auto, …" (WP 6.7+) for all lazy-loaded images. By default the plugin now keeps core's layout-aware sizing and only strips auto from small, attribute-sized images (see the next filter).

add_filter( 'mwe_etchwp_disable_auto_sizes', '__return_true' );

mwe_etchwp_auto_sizes_min_width

Width attribute (in px) below which an image is treated as attribute-sized: the plugin writes no srcset/sizes attributes for it and it loses core's auto sizes keyword (via the wp_content_img_tag guard). Small images with no CSS sizing (icons, slider arrows) would otherwise be laid out at container width. Default 150.

add_filter( 'mwe_etchwp_auto_sizes_min_width', function () {
    return 200;
} );

Available Constants

MWE_ETCHWP_IMAGE_ENHANCEMENT

Enable/disable image enhancement feature.

define( 'MWE_ETCHWP_IMAGE_ENHANCEMENT', false );

MWE_ETCHWP_FOCUS_POSITION

Enable/disable focus position feature.

define( 'MWE_ETCHWP_FOCUS_POSITION', false );

MWE_ETCHWP_GITHUB_TOKEN

GitHub Personal Access Token to avoid API rate limits when checking for updates. Without a token, GitHub limits requests to 60/hour which can cause "Could not determine if updates are available" errors.

define( 'MWE_ETCHWP_GITHUB_TOKEN', 'ghp_your_token_here' );

To create a token:

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token with public_repo scope (for public repositories, no scope is actually needed)
3. Add the constant to your wp-config.php

Class Architecture

MWE\EtchWP_Enhancements\
├── Plugin                    # Main plugin class with dependency checks
├── Image_Enhancement         # Handles image attribute enhancement
├── Focus_Position            # Handles focus point integration
├── Focus_Dynamic_Data        # Exposes focus points in Etch Dynamic Data
├── Focus_Ajax                # AJAX handlers for focus point overrides
├── Focus_Editor_UI           # Loads focus point editor UI in Etch canvas
└── Helper                    # Shared utility functions

All classes use the Singleton pattern and are autoloaded.

Hook Priorities

• render_block: Priority 15 (runs after Etch at priority 10)
• wp_get_attachment_metadata: Priority 10
• plugins_loaded: Plugin initialization

File Structure

mwe-etchwp-enhancements/
├── mwe-etchwp-enhancements.php       # Main plugin file
├── README.md                          # This file
├── readme.txt                         # WordPress.org readme
├── includes/
│   ├── class-plugin.php              # Main plugin class
│   ├── class-image-enhancement.php   # Image enhancement feature
│   ├── class-focus-position.php      # Focus position feature
│   ├── class-focus-dynamic-data.php  # Etch Dynamic Data integration
│   ├── class-focus-ajax.php          # AJAX handlers for overrides
│   ├── class-focus-editor-ui.php     # Editor UI asset loading
│   └── class-helper.php              # Shared utilities
├── assets/
│   ├── js/
│   │   └── focus-point-editor.js     # Visual focus point editor
│   └── css/
│       └── focus-point-editor.css    # Editor UI styles
└── languages/
    └── mwe-etchwp-enhancements.pot   # Translation template

WordPress Coding Standards

This plugin follows:

• WordPress PHP Coding Standards
• WordPress Documentation Standards
• PSR-4 autoloading with namespace MWE\EtchWP_Enhancements
• Strict typing with declare(strict_types=1)

Changelog

1.2.12 - 2026-09-04

• Changed: WordPress core sizes="auto, …" is no longer disabled site-wide; layout-aware image sizing stays enabled and a per-image guard strips auto only from small attribute-sized images (#8)
• Added: mwe_etchwp_disable_auto_sizes filter to restore the previous global disable (#8)
• Added: mwe_etchwp_auto_sizes_min_width filter controlling the attribute-sized threshold; invalid values are clamped to at least 1 (#8)
• Changed: attribute-sized images (width below the threshold) no longer receive srcset/sizes from the plugin; the browser sizes them from their width attribute (#10)
• Fixed: over-fetching on lazy-loaded content images (e.g. a lazy header logo fetched 2048w instead of 768w on large viewports) (#8)

1.2.11 - 2026-08-11

• Fixed: AJAX request deduplication in focus point editor - concurrent requests for the same image now share a single request instead of firing duplicates
• Fixed: Combobox selector compatibility with Etch 1.6.x (updated from .etch-combobox__input to .etch-combobox__native-input)
• Improved: Code style in promise caching functions
• Verified: Compatibility with Etch 1.6.7 (block names, HTML output, sidebar/properties/combobox selectors, WP Media ID label, plugin detection, iframe title, hook priorities)

1.2.10 - 2026-05-29

• Added: Focus point editor support for the Etch Dynamic Image element (etch/dynamic-image)
• Added: Picker is shown when a Dynamic Image has a fixed WP Media ID, reusing the etch:img focus point flow
• Added: Explanatory notice for Dynamic Images with a dynamic source (e.g. loop expressions), directing users to set focus points per image in the Media Library
• Verified: Regular image and etch:img pickers remain unaffected; no false detection of dynamic image panels

1.2.9 - 2026-05-29

• Fixed: Focus point editor tag detection in Etch 1.4.x (the .etch-combobox__input class was renamed to .etch-combobox__input-wrapper)
• Added: Support for the new Etch 1.4.x combobox markup while remaining backward compatible with Etch 1.3.x and earlier
• Verified: Compatibility with Etch 1.4.19 (block names, etch:img rendering, sidebar/properties selectors, iframe title, plugin detection)