Block API v2

Introduction

Since WordPress 5.6, the block editor has a new version of the Block API. The ACF 5.10 release introduced support for the Block API v2. This is only available when ACF is installed on sites using WordPress 5.6 and above.

Changes

The block wrapper element for ACF Blocks with Block API v2 support now have a predefined class of wp-block-{name}, where name is generated from the name of the block. This is in line with the changes to how the block editor defines the default wrapper element.

<div id="testimonial-block_6126540e5e5e2" class="testimonial wp-block-acf-testimonial">

Block API v2 support also gives ACF developers the ability to use the block editor’s filters. These filters allow you to change the behavior of your ACF blocks while you are editing content using the block editor. Currently, ACF only supports updating the className property of a block.

Getting Started

1. Register a Block using acf_register_block_type

To use the block editor filters, you will need a custom ACF block. For the purposes of this tutorial, we’ll be using the Testimonial Block detailed in the acf_register_block_type documentation.

2. Register a block editor script

To register block editor filters, you will need a custom JavaScript file, which is enqueued with the editing interface. To do this, enqueue a JavaScript asset in your theme, child theme, or plugin, and make sure that it lists wp-blocks as a dependency.

add_action( 'enqueue_block_editor_assets', 'acf_blocks_editor_assets' );
function acf_blocks_editor_assets() {
    wp_enqueue_script(
        'acf-block-editor-assets-js',
        get_stylesheet_directory_uri() . '/assets/js/acf-block-editor-assets.js',
        [ 'wp-blocks' ]
    );
}

Ensure that the editor assets JavaScript file exists in the right place, in this case /assets/js/acf-block-editor-assets.js, and it will be enqueued whenever the block editor interface is used in WordPress.

3. Add a filter

You can now hook into the relevant block editor filter in your custom JavaScript file by using the wp.hooks.addFilter method. Similar to WordPress PHP filters, this method accepts a series of parameters.

addFilter( 'hookName', 'namespace', callback, priority )

For the purposes of this tutorial, we’ll be hooking into the blocks.getSaveContent.extraProps filter hook, defining our own acfBlocks/addACFExtraProps namespace, and calling the addACFExtraProps callback function we define.

wp.hooks.addFilter(
    "blocks.getSaveContent.extraProps",
    "acfBlocks/addACFExtraProps",
    addACFExtraProps
);

Once we have set up the filter, we can create the addACFExtraProps function to handle the callback functionality. This function will only apply the changes to our acf/testimonial block and assign an extra className value of ‘acf-testimonial’ to the extraProps object.

function addACFExtraProps(props, blockType, attributes) {
    if (blockType.name !== 'acf/testimonial') {
        return props;
    }
    props = Object.assign( props,
        {
            className: 'custom-testimonial'
        } );
    return props;
}

3. Add and save your block

If you add the Testimonial block to a page, save it and preview the page, you can see how the additional class is appended to the rendered ACF Testimonial block. This is because every time the block content is saved, the blocks.getSaveContent.extraProps filter is fired, triggering our addACFExtraProps function.

acf-block-editor-filters-class-name
Screenshot of the source code for the custom Testimonial block, showing the custom-testimonial class.

We use cookies to offer you a better browsing experience, analyze site traffic and personalize content. Read about how we use cookies and how you can control them in our Cookie Policy. If you continue to use this site, you consent to our use of cookies.