Introducing the ACF PRO Block Versioning Developer Preview

[lgladdy]

Introducing the ACF PRO Block Versioning Developer Preview

[Update 3, 20th July 2022]
We've released a forth developer preview build with some further bug fixes, you can find the details of those further changes here.

[Update 2, 27th June 2022]
We've released a third developer preview build, you can find the details of those further changes here.

[Update 9th June 2022]
We've released a second developer preview build, you can find details of the further changes in that release here.

In the last few releases of WordPress, Gutenberg has made significant changes to all aspects of the block editor and block registration, and many of you have raised issues and feature requests to improve ACF Blocks with those improvements.

For our next release of ACF, we’re aiming to bring some key new features to ACF Blocks to take advantage of those new features from Gutenberg, as well as improving existing blocks. We’re releasing a preview build today, early in our development cycle, so we can get your feedback and bug reports early in development.

You can download this preview (tagged as 6.0.0-alpha1) from your account now. This build is ACF PRO 5.12.2 with the following changes:

Block.json support

Since WordPress 5.8, WordPress has supported - and recommended - that blocks are registered through a JSON configuration file. All of the WordPress Block Documentation was migrated to only show block.json configuration objects, and it became confusing for users to know what WordPress configuration options were usable in ACF PRO. This build introduces support for block.json registration of blocks with ACF.

For blocks registered through a block.json file, you can mark them as ACF Blocks by adding a new ACF configuration key to the JSON file, which contains the ACF specific configuration, for example:

{
    "name": "all-fields-block",
    "title": "All Fields Test Block",
    "description": "All fields test block",
    "style": "file:./all-fields-block.css",
    "category": "theme",
    "icon": "admin-comments",
    "apiVersion": 2,
    "keywords": [
        "test",
        "quote"
    ],
    "acf": {
        "mode": "preview",
        "renderTemplate": "all-fields-block.php"
    },
    "styles": [
        { "name": "default", "label": "Default", "isDefault": true },
        { "name": "red", "label": "Red" },
        { "name": "green", "label": "Green" },
        { "name": "blue", "label": "Blue" }
    ],
    "supports": {
        "align": true,
        "anchor": true,
        "alignContent": false,
        "color": {
            "text": true,
            "background": true,
            "link": true
        },
        "alignText": true,
        "spacing": {
            "margin": [
                "top",
                "bottom"
            ],
            "padding": true
        },
        "typography": {
            "lineHeight": true,
            "fontSize": true
        },
        "fullHeight": true
    },
    "attributes": {
        "backgroundColor": {
            "type": "string",
            "default": "purple"
        }
    },
    "example": {
        "attributes": {
            "data": {
                "text": "This is an example text field",
                "text_area": "This is an example text area field"
            }
        }
    }
}

You then need to use the standard WordPress block registration function register_block_type, rather than acf_register_block_type:

register_block_type( 'path/to/folder/containing/block.json' );

If you don't specify a namespace for your block like in our example above: "name": "all-fields-block",, ACF will automatically add it if it is an ACF block to become the equivalent of "name": "acf/all-fields-block",

Upon release, this new method of registering blocks will become the recommended way to register a block, replacing the acf_register_block_type function.

The renderTemplate property should either be a full path to the template file, or relative to the location of the JSON file.

WordPress uses a camelCase format inside JSON files, and ACF adopts that too. Configuration keys such as render_template when used in acf_register_block_type need to be renderTemplate when used in JSON, likewise align_content and full_height should be alignContent and fullHeight for example. All previous configuration objects are supported, except for enqueue_style, enqueue_script and enqueue_assets for the following reason:

Asset Loading

When ACF Blocks was first introduced, it supported enqueueing block specific assets before WordPress had native support. Recent (and upcoming) updates to Gutenberg will require these assets to be loaded using specific WordPress asset configuration keys such as editorScript, script, editorStyle and style.

WordPress 5.9 users who use Block Styles may have noticed that the ACF registration of styles was not applied to those previews, which is why all ACF Block users should migrate their blocks to use those WordPress provided methods of asset loading.

The previous methods of asset loading in ACF Blocks will continue to work for the time being in acf_register_block_type, but as WordPress continues to make changes across releases we expect that to stop working.

Block ID removal

This release of ACF will remove saved block IDs from ACF Blocks. This means you can easily copy and paste blocks, simplify your post type templates or block patterns, or duplicate blocks without having any issues where block IDs clash.

We’re hoping this change is transparent to users, and any existing blocks will have their block IDs removed the first time they’re edited after installing this build. We’ll still generate a $block['id'] for your templates as we know some users use that for element IDs, but the format of those IDs will change, and may be duplicated if you have multiple blocks on the same page with the exact same data (similar to how block IDs are the same inside a query loop block now)

Because of this, if you want to downgrade to ACF 5.12 after installing this build, you may experience warnings in your templates until you edit a block if you are relying on $block['id'] in a template without checking if it exists.

Block Versioning

One of the issues we’ve had with ACF Blocks development is that we haven’t been able to react to new Gutenberg features as fast as we’d like due to the requirement to maintain backwards compatibility with blocks created potentially as far back as WordPress 5.3.

This release of ACF brings block versioning, meaning we can make backwards compatibility breaking changes whenever necessary, allowing users to opt in to them to enable new features.

A new blockVersion (inside the ACF key in block.json) or acf_block_version (if using acf_register_block_type) key is now supported. For blocks registered via block.json, this defaults to 2, and for acf_register_block_type, this defaults to 1.

For now, the only change between the two versions is the way <InnerBlocks /> markup is rendered. If you use block version 2 (which requires WordPress 5.8+), the container markup when using InnerBlocks will match between backend and frontend rendering, with any inner blocks wrapped in a new (and single level) <div class="acf-inner-blocks-container"></div> element. This can help make your CSS layouts easier, as you can be sure both render views have the same markup.

Block Registry Standardization

In previous versions of ACF PRO, a lightweight shim of the block configuration was registered in PHP, and then the full configuration registered in JS.

In this build of ACF the full block configuration is now saved in the WordPress PHP Block Registry. This makes it easier for you to access details of the block configuration in your templates or render callback should you wish.

Block Bug Fixes

We’ve fixed a few reported bugs with ACF Blocks in this build as well. For example, content after <InnerBlocks /> will now render correctly without the need to wrap it in another div, and alignText will now always default to the WordPress default of left rather than an empty string.

Wrap up

We hope you’ll take the time to test this build of ACF - we’re particularly interested in feedback on how your upgrades go to make sure there are no issues with the block ID removal system.

Please leave any comments, bugs or feedback here on this GitHub issue. We’ve left a few debug console messages in this build to try and help us detect any issues with block preloading or rendering, so screenshots of your browser console will likely be especially useful with any bug reports!

[JiveDig]

This is great news, thanks for the hard work thus far! I have a few quick questions that will likely help others test as well.

1. Can we see an example of loading/enqueuing assets the new way?
2. Is this new way only relevant when registering blocks via JSON?

I can't wait to test out the v2 markup changes :)

[lgladdy]

@JiveDig

1. Sure! You can see an example in the block.json above on how to include assets, and more details on the WordPress docs (as you can pass in a script/style handle if you've already registered it).

Specifically:

"style": "file:./all-fields-block.css",

That's loading a file called "all-fields-block.css" in the same folder as the block.json whenever the block is added to a page.

2. That's actually a good question - and I took a quick look at the WordPress core code for register_block_type_from_metadata which is the function it uses internally, and it looks like the functions for that are exclusive to that function which isn't executed for the old way. So I think the answer is no. Edit: Turns out, this will work - but you need to pass a script or style handle that has previously been registered outside of the block.

I'll look into this a bit deeper to see if we can manually add support for it, but that might not be possible for other reasons that is specific to the block.json loading.

[JiveDig]

Okay great, thanks.

1. Duh! I looked too quickly and was looking for the word register, enqueue, or asset, not "style" or "script".
2. We have some complex blocks with field groups registered in PHP. I'm not super clear on how to convert them to JSON and still register the fields in PHP for those blocks, but I'll dive in a bit ASAP.

[lgladdy]

@JiveDig Yeh - we definitely will get migration guides and such in the release documentation. Let me know if you need any help though. For my own dev test blocks I actually just copy/pasted the PHP array and converted it to JSON format, but you could always do:

echo json_encode($block_configuration_array, JSON_PRETTY_PRINT);
die();

to get the start point out from the PHP code for the old way!

[JiveDig]

I got ya. I was thinking acf_add_local_field_group() was also moving to JSON somehow. Registering the actual block in JSON will be an easy conversion. Registering field groups in JSON would definitely not be fun :)

[CreativeDive]

@lgladdy oh wow, a lot of changes. I will need some time to test all of this changes. But here is my first feedback. I have created this issue #655

It seems this is already fixed by the new alpha version. The field values are now present :-)

[CreativeDive]

@lgladdy it seems there is something broken with the default alignText change to left.

I have registered a block like this:

acf_register_block_type(
	array(
		'name' => 'button',
		'title' => __('Buttons', 'wphave'),
		...
		'align_text' => 'left', // --> Optional default value
		'supports' => array(
			'align_text' => true, // --> Enable the text alignment control
			...
		),
		...
	)
);

In a specific post I have used this block and the align_text was set to center.

Before the new alpha version, everything looks good with the alignment. After using the new alpha now this align_text is set to left. But before it was saved to center.

It seems there is something wrong and should be improved.

[CreativeDive]

@lgladdy For now, the change from removing block IDs looks good. The block IDs no longer exist.

I have copied some ACF blocks and made changes to each copied block and it seems there are no longer issues with the field values was set to a wrong block.

But this issue #605 is still there:

May-13-2022.08-58-41.mp4

It only works properly after the post has been saved and reloaded. But not if the block was only inserted after copying. Then correct field changes are not present.

Is there any hope to get this fixed?

[CreativeDive]

@lgladdy this issue #650 is fixed by using the new alpha. Thank you.

[CreativeDive]

@lgladdy the $block var still contains the "id" attribute:

error_log(print_r($block,true));

...
[id] => block_b11dfd57e4d7a1b736e8632b9b0fcbca
...

This id is no longer used for allocating ACF blocks. Thank you! But will this attribute remain in the $block var in the future?