Block Transforms

Overview

The plugin registers block transforms that let users convert between core WordPress blocks and ACF blocks directly in the editor. When you select a compatible core block, the block toolbar shows an option to transform it into the corresponding ACF block.

Transforms are registered via assets/js/block-transforms.js, which is enqueued on enqueue_block_editor_assets. The script uses the blocks.registerBlockType filter from wp.hooks to add transform definitions.

Available Transforms

Code Block

• core/code to acf/code-block – Extracts the code content (stripping HTML) and maps it to the code_content field. Language defaults to plaintext, theme to dark.
• core/preformatted to acf/code-block – Same as above. Preformatted content is treated as plain code.
• acf/code-block to core/code – Extracts code_content from the ACF block data and passes it to the core block.

Checklist

• core/list to acf/checklist – Extracts list items from the core list block (handles both modern innerBlocks with core/list-item children and the legacy values attribute). Each item becomes a checklist row with checklist_item_text and checklist_item_checked (defaults to unchecked). Default accent color is #16a34a, background is #f9fafb.

Changelog

• core/list to acf/changelog – Extracts list items and creates a changelog entry with version 1.0.0, today’s date, and all items typed as added. The data is structured as a nested repeater (entries containing items).

Video

• core/video to acf/video – Detects the video source type from the URL (YouTube, Vimeo, or self-hosted) and maps attributes like caption, autoplay, loop, muted, and controls. If a poster image is set, it’s preserved. Aspect ratio defaults to 16-9.

How Transforms Work

The script uses an IIFE (Immediately Invoked Function Expression) pattern for ES5 compatibility. It registers four blocks.registerBlockType filters, one per target block. Each filter intercepts the block registration and appends transform definitions to the block’s transforms.from and/or transforms.to arrays.

Data Format

ACF block transforms set field values on the data attribute of the new block. For simple fields, this is straightforward:

createBlock( 'acf/code-block', {
    data: {
        code_content: codeContent,
        code_language: 'plaintext'
    }
});

For repeater fields, the flat indexed format is used (which the compatibility layer can read):

// Helper builds: { items: 3, items_0_text: "...", items_1_text: "...", ... }
var data = buildRepeaterData( 'checklist_items', items, {
    checklist_item_text: function( text ) { return text; },
    checklist_item_checked: 0
});

The buildRepeaterData() helper in the script creates the flat key structure that ACF expects for repeater fields saved from the editor.

Limitations

• Transforms are one-directional for most blocks (core to ACF). Only the code block supports bidirectional transforms.
• List-to-checklist and list-to-changelog transforms extract plain text only. HTML formatting inside list items is stripped.
• The changelog transform creates a single entry with today’s date. You’ll need to edit the version number and date manually.