WPCalibrate Block Linker

Transform core Gutenberg container and layout blocks into accessible, clickable cards and banners with automatic safe interactive handling, clean HTML5 standards, and zero frontend database bloat.

Table of Contents

• About
• Key Features
• The Dual-Strategy Architecture
• Supported Blocks
• How to Use
• Developer Filters & Extensibility
• Automatic Dashboard Updates via GitHub
• Frequently Asked Questions (FAQ)
• Changelog
• License & Support

About

Most existing block linking solutions for WordPress blindly wrap entire blocks in an HTML <a> tag. When a card or container contains inner links, buttons, form controls, audio/video elements, or interactive components, wrapping them in an outer anchor generates invalid HTML5. Browsers attempt to auto-correct the invalid markup by splitting or duplicating anchor tags, resulting in broken layouts, invalid DOM trees, and dysfunctional inner buttons.

WPCalibrate Block Linker solves this problem permanently. Built specifically for the modern WordPress Block Editor (Gutenberg) and Full Site Editing (FSE), it uses an automatic two-strategy engine:

1. Strategy A (Semantic Anchor Mode): For static container blocks, outputs pure HTML5 semantic anchor tags with native accessibility and zero client-side JavaScript overhead.
2. Strategy B (Safe Delegated Interaction Mode): When nested interactive elements are detected via server-side DOM analysis, outputs standard ARIA link semantics (role="link", tabindex="0") and delegated event handling. Inner links, buttons, and form inputs remain 100% functional without triggering parent container navigation.

Key Features

• Automatic Two-Strategy Engine: Dynamically selects the cleanest, most accessible HTML markup based on descendant elements.
• Child Interactive Safety Shield: Inner buttons, links, form controls, dropdowns, audio, video, and interactive ARIA elements retain independent click behavior.
• Native Block Editor Sidebar Controls: Integrates seamlessly into the Gutenberg sidebar using WordPress editor components.
• Internal Content Search & External URLs: Search posts, pages, and custom post types (including WooCommerce Products) directly within the editor.
• SEO & Security Controls: Toggle target="_blank" with automatic rel="noopener", plus strict rel="nofollow" and rel="sponsored" token normalization.
• Zero Frontend Database Bloat: Executes 0 database queries on page render.
• Conditional Asset Loading: Vanilla JavaScript runtime (~1.5KB) and styles are enqueued on-demand only on pages containing linked blocks.
• WCAG 2.1 AA Keyboard Accessibility: Full keyboard navigation (Tab focus and Enter key activation) while preserving Spacebar for native scrolling and form controls.
• Text Selection Protection: Highlight and copy text inside clickable containers without accidentally triggering navigation.
• Shared WPCalibrate Admin Suite: Coexists seamlessly under the shared wpcalibrate admin menu without duplicate parent menus.

The Dual-Strategy Architecture

Supported Blocks

Out of the box, WPCalibrate Block Linker supports:

• core/group
• core/columns
• core/column
• core/cover
• core/media-text

How to Use

1. Select a Container Block: In the Block Editor, select any supported container block (e.g. Group or Column).
2. Enable Block Linker: In the block settings sidebar on the right, open the Block Linker panel and switch Enable Block Linker to On.
3. Configure Link Options:
   • Search for an internal post/page or paste an external URL.
   • Toggle Open in new tab (automatically applies rel="noopener").
   • Toggle Add rel="nofollow" or Add rel="sponsored" for SEO control.
   • Enter an optional Accessible Label (aria-label) for assistive screen readers.
   • Add optional Custom CSS Classes to the clickable container.
4. Publish: Publish or update your post. The frontend automatically applies the appropriate strategy.

Developer Filters & Extensibility

WPCalibrate Block Linker provides clean WordPress filter hooks for developers and agencies:

1. Extend Supported Blocks (PHP)

add_filter( 'wpcalibrate_block_linker_supported_blocks', function( array $blocks ): array {
    $blocks[] = 'my-theme/hero-box';
    $blocks[] = 'acf/custom-card';
    return $blocks;
} );

2. Extend Supported Blocks in Gutenberg (JavaScript)

wp.hooks.addFilter(
    'wpcalibrateBlockLinker.supportedBlocks',
    'my-theme/supported-blocks',
    function( blocks ) {
        return [ ...blocks, 'my-theme/hero-box' ];
    }
);

3. Override Render Strategy (PHP)

add_filter( 'wpcalibrate_block_linker_strategy', function( string $strategy, array $block, string $content ): string {
    // Force delegated mode for specific block structures
    return 'delegated';
}, 10, 3 );

4. Custom Wrapper CSS Classes (PHP)

add_filter( 'wpcalibrate_block_linker_wrapper_classes', function( array $classes, array $parsed ): array {
    if ( $parsed['is_new_tab'] ) {
        $classes[] = 'has-external-indicator';
    }
    return $classes;
}, 10, 2 );

Automatic Dashboard Updates via GitHub

This plugin supports direct updates through the WordPress administrative dashboard when releases are published on GitHub.

The main plugin file contains standard update headers:

/*
 * GitHub Plugin URI: https://github.com/zeeshanraza-official/wpcalibrate-block-linker
 * Primary Branch:    main
 * Release Asset:     true
 */

To enable automated updates inside your WordPress dashboard, install the free GitHub Updater or Git Updater plugin. WordPress will check for new GitHub releases and allow 1-click updates directly from Dashboard > Updates.

Frequently Asked Questions (FAQ)

How does Block Linker handle nested buttons or links?

Block Linker scans block HTML descendants using WordPress's WP_HTML_Tag_Processor. If inner links, buttons, or form controls are detected, it switches to Strategy B (Safe Delegated Interaction Mode), allowing children to be clicked without triggering parent navigation.

Does this plugin slow down page loading?

No. WPCalibrate Block Linker executes zero database queries on frontend page renders. Its vanilla JS script (~1.5KB) and styles are enqueued conditionally only on pages that contain an active linked block.

What happens if I deactivate the plugin?

Deactivating the plugin safely stops container link navigation. Your block content, layouts, and inner elements remain completely safe and uncorrupted. Saved attributes remain inert inside standard block comments without causing block validation errors.

Changelog

1.0.1

• Fixed dashboard menu icon sizing and distortion via scoped admin CSS in admin_head.
• Added dedicated Overview tab with 4-step quick-start guide, dual-strategy comparison matrix, and developer filters reference.
• Overhauled admin layout with modern aesthetics, elevated feature cards, responsive header, and pill status badges.
• Added GitHub updater headers for dashboard updates.

1.0.0

• Initial production release.
• Support for core Group, Columns, Column, Cover, and Media & Text blocks.
• Automatic Two-Strategy Engine (Semantic Anchor and Safe Delegated Interaction).
• Shared WPCalibrate parent menu integration with collision protection.
• Full WCAG 2.1 AA keyboard accessibility compliance.

License & Support

• License: GPLv2 or later
• Author: WPCalibrate
• Support: support@wpcalibrate.com
• Website: https://wpcalibrate.com