4 Aug

ACF PRO 6.0 Beta 1

By Iain Poulson

We’re excited to announce the first beta release of ACF PRO 6.0. ACF PRO v6.0.0-beta1 is now available with improved performance for Repeater fields with large datasets, and a new generation of ACF Blocks. 🎉🥳

Repeater Pagination

Over the years we have had many support requests from users who have been storing a large amount of data in Repeater fields. This can result in performance issues for the users filling out the data.

Currently, when a user loads the edit page in the WordPress dashboard, ACF loads all the rows of data with all the subfields for each row. Depending on the number of rows and subfields, this can take some time, increasing the overall admin page load time and blocking the user from performing actions like saving the post.

When the post is saved, ACF will send all the subfields for every row back to the server to be updated, even if the data hasn’t changed. This can lead to memory issues, running into the PHP max_input_vars setting, and the data not being saved correctly.

With the 6.0 release we have introduced a new setting for the Repeater, which enables pagination of the records when editing the data.

Please note, the pagination setting is opt-in. It is not enabled by default and will not be turned on for existing repeaters. Not all repeaters will benefit from this setting, as there are a number of user experience changes to allow for pagination.

Enabling Pagination

You can enable pagination by editing a repeater field and turning on the “Pagination” setting. Once enabled, a new “Rows Per Page” setting will be displayed as well:

The new repeater pagination settings

Things to Note

As mentioned above, there are some user experience changes unique to paginated repeaters.

With standard repeaters, you could reorder rows via a drag-and-drop interface. This doesn’t work with paginated repeaters, as you may need to move an existing row to a different page. Instead, we’ve added the ability to reorder rows by clicking the row number – this will reveal a number input which can be used to designate where the row should be moved to:

A screenshot showing how a row can be reordered.

Once you designate a new row number and update the page, the row will be moved to the new location.

Rows that have been inserted in between existing rows and duplicated rows cannot be reordered until the page has been updated. As such, there is currently no row number displayed next to these rows. We’re looking into adding a useful placeholder here to better illustrate that these new rows have been added, but cannot be reordered.

Also, repeater pagination will not work for fields used inside an ACF Block, as there would be no performance benefit given the repeater data is already stored in the DOM.

With all that said, we’re really excited to have paginated repeaters available in this beta. If you’ve worked with repeater fields before and would like to test this out, please give it a try and let us know if you see any issues.

ACF Blocks

In the last few releases of WordPress, Gutenberg has made significant changes to all aspects of the block editor and block registration, and this has impacted ACF Blocks. We’ve not been able to move as fast as we would have liked on implementing changes to support these new features for back compatibility reasons, so are excited to announce that ACF 6.0 contains a new block versioning system, allowing you to opt in to new versions which will change things like the markup and structure of ACF Blocks in both the backend and frontend, and may require updates to your theme to support.

ACF 6.0 includes ACF Blocks Version 2. This next generation of ACF Blocks brings us much closer to the native block experience, while still giving you the PHP based templating language you know as a WordPress developer.

Many of our fixes will also apply to existing ACF Blocks. These will remain supported for as long as WordPress supports the previous methods of block registration.

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. ACF 6.0 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:

block.json

{
    "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",
        "postTypes": [ "post" ],
    },
    "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" although you are now free to use your own namespace for your blocks.

Upon final 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.

You can also now specify default attributes for your block, as shown in our example above in the attributes key. You can use this to set defaults for the WordPress provided block attributes, such as backgroundColor.

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 reasons explained below:

Block 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 affects all versions of ACF Blocks and 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 ACF 6.0. 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 Details

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. For acf_register_block_type, this defaults to 1.

For now, the main 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.

Whilst this wrapper must appear in the backend block editor, if you wish to disable it for the frontend, you can do that with a new filter, and optionally enable or disable it based on the block name:

add_filter( 'acf/blocks/wrap_frontend_innerblocks', 'acf_should_wrap_innerblocks', 10, 2 );
function acf_should_wrap_innerblocks( $wrap, $name ) {
    if ( $name == 'acf/test-block' ) {
        return true;
    }
    return false;
}

If you just wish to modify the class being used for the wrapper, instead of the default acf-inner-blocks-container you can simply add a class to your <InnerBlocks /> tag inside your block template, such as …

<InnerBlocks class="test-wrapper-class second-class" />

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 callbacks.

Block Context Changes

During development, we saw a conversation on Twitter discussing the viability of using data from an ACF Block inside blocks contained in its <InnerBlocks> children.

We suspected this would be possible using block context, the system things like the Query Loop block uses to know the current post type.

ACF 6.0 introduces support for block context. This means if you want to pass ACF field data from a parent block to an InnerBlock, the InnerBlock will automatically reload the template, showing changes live as you make changes to fields in the parent. This support should also improve the reliability of blocks used inside Query Loop blocks.

To enable this, you need to tell WordPress to share the ACF data attribute to its child blocks with a custom key (acf/fields in our example) with providesContext in block.json:

"providesContext": {"acf/fields": "data"}

Then, to consume that context in an ACF block, you need to pass the context key in usesContext:

"usesContext": ["acf/fields"],

One thing to note: ACF Blocks use field keys in the block editor, and block data is only hydrated to field names upon save. Because of this, you should use $context['acf/fields']['field_key'] to get access the data inside your template if it exists before defaulting back to $context['acf/fields']['field_name'] if it doesn’t to support both backend and frontend output of context data.

Blocks Without Fields

With Full Site Editing and the Query Loop block, it’s now much more likely you might want to use ACF Blocks without any specific fields attached to the block, for example because it’s showing post templating elements like titles or post content, or because you want to display fields which are added on the post being displayed, rather than from the block.

ACF 6.0 adds support for this by providing advisory text when a block has no fields assigned, whereas previously the block’s edit mode would simply be blank and not selectable.

Developers who wish to modify the default advisory text can do so with the new acf/blocks/no_fields_assigned_message filter which offers 2 parameters: the message to be displayed and the name of the block it will be displayed on.

Block Bug Fixes

We’ve also fixed a number of other bugs which apply to all versions of ACF Blocks.

  • The render_block_preview JavaScript event is now always fired every time a block preview is displayed, rather than just the first time.
  • Accordion fields inside an ACF block now are styled to match the native sidebar experience of the block editor.
  • ACF Block preloading now works again for blocks saved in edit mode, and for blocks without any saved field data (due to changes in block preloading for the removal of Block IDs, you may need to edit each block once before it can be preloaded.)
  • ACF Block edit forms will now behave correctly if they’re not visible when loaded.

Thank Yous

We’d like to thank all of our GitHub developer preview users for their help in getting ACF 6.0’s block changes ready for release. Across the 4 developer previews (tagged as ACF 6.0.0-alpha#) we’ve fixed numerous bugs and implemented several additional new features based on your feedback, and we can’t wait to see what you develop with ACF Blocks in ACF 6.0!

Translation Improvements

ACF 6.0 introduces a new way of collecting translations from our wonderful contributors. For all the strings contained in the free version of ACF, these are now collected from translate.wordpress.org

This means ACF 6.0 introduces 10 new languages (or language variants) and updates almost all of the existing ones.

Many of you have submitted translations for numerous languages on WordPress.org since that translation functionality was introduced, but until this release they were never included or loaded into ACF. We’ve imported all the contributions we’ve received directly from our users into translate.wordpress.org for languages which weren’t already complete. These should be reviewed by the WordPress language editors over this beta cycle.

The existing languages we bundled in ACF have been trimmed where they are already complete and approved on translate.wordpress.org to only include the pro strings, but where a language is not complete, we’ve kept all the free strings included too, to avoid losing data while we wait for approval.

If you’d like to help us translate ACF to your language, or help verify translations for your language, you can do so on translate.wordpress.org. WordPress’s Translation Handbook has everything you need to get started. Once complete, you can request WordPress’s translation editors review your submissions as detailed here, or you can request to become a Project Translation Editor, where you can take control over ACF’s translations for your language.

For strings specific to the PRO version of ACF, we’ve updated our .pot file generation to only include PRO strings, and you’ll find these files inside a new folder on our GitHub repository, /lang/pro. Whilst today’s Beta 1 release is only for ACF PRO, we’ve manually updated the ACF Free repo with the new translations so you can start translating during this cycle.

To avoid ACF Free and ACF PRO having divergent translations, updates from translate.wordpress.org will not take effect in either version until each ACF release going forward.

Please let us know if you experience any issues with the new translations, and we can’t wait to see what languages you add support for next. English (Pirate) anyone?

What’s Next

We are planning another beta release this month with the first look of a plugin UI refresh, which brings an improved user experience to field groups and adding and editing fields.

The final 6.0 release will also contain a number of accessibility fixes, so look out for a release candidate coming soon.

Full Changelog (WIP)

New – Repeaters now have an optional “Pagination” setting which can be used to control the number of rows displayed at once.
New – ACF Blocks now have a versioning system allowing developers to opt in to new features.
New – ACF Blocks now support version 2, enabling block.json support, reduced wrapper markup, and significant other new features.
New – ACF Blocks now use Block IDs saved in the block comment.
Enhancement – Bulk actions for field groups now include “Activate” and “Deactivate” options.
Fix – ACF Blocks preloading now works for blocks saved in edit mode.
Fix – ACF Blocks edit forms now behave correctly if they are not visible when loaded.
Fix – ACF Blocks now always fire render_block_preview events when a block preview is displayed or redisplayed.
Fix – ACF Blocks with no fields now display advisory text and are selectable in the block editor. This message is filterable with the acf/blocks/no_fields_assigned_message filter, providing both the message to be displayed and the block name it’s being displayed against.
Fix – Accordions inside ACF Blocks now match the current native block styling.
Fix – ACF Blocks which contain no fields now preload correctly.
Fix – Changes to an ACF Block’s context now trigger a re-render.
Fix – The field “move” option now no longer displays for fields when only one field group exists.
Fix – Language for field group activation state now standardized to “active” and “inactive.”
Fix – SVGs containing foreignObject tags now correctly render in JSX rendered ACF Blocks.
i18n – ACF translations are now synced with contributions from translation.wordpress.org at each release, increasing ACF’s supported languages and updating many other translations. PRO strings should still be submitted as pull requests on GitHub (Additional thanks to maximebj, emreerkan and Timothée Moulin for their contributions which are included here).

About the Author