Connecting block attributes and custom fields & Block Bindings API for WP 6.5

[SantosGuillamot]

Part of:

• Block API #41236
• Custom fields connected to Blocks #51373
• Block Bindings API iteration for 6.5 #54536

Related to:

• Pattern Overrides epic (WordPress 6.5) #53705.
• Create a system for inserting site/post metadata into generic blocks #37753.
• Inline Dynamic Content Solutions #21932.

---

EDIT: Connecting block attributes and custom fields, and the block bindings API tracking issues have been merged into this epic because they are highly related and it seems it is easier to follow having everything under the same discussion.

This issue is meant to keep track of and discuss how to connect block attributes with custom/meta fields and how Block Bindings API should work. It includes a list of tasks needed for this, and we will share updates about the progress here.

• Block Bindings API: Internal API to connect block attributes and different sources. Not only used for custom fields but for other projects like Partially Synced patterns.
• Custom Fields: Using the Block Bindings API, support for the "meta_fields" source to connect block attributes and custom fields.

For more context about the reasoning of the block bindings API, you can take a look at its original tracking issue.

Progress

This is a list of things to consider/questions related to the Block Bindings API that will be updated as we go along:

WordPress 6.5 release process

Click to see the list of issues addressed during 6.5 release cycle

---

A couple of things that are important:

• This project depends on the Block Bindings API: link.
• We will start supporting just a few core blocks attributes that can be increased in a later phase. We can start with:
  • Paragraph content.
  • Heading content.
  • Image URL.
  • Button link and content.

Fixes/updates for Gutenberg 17.6 RC (Tuesday 30th)

• Decide the final name of the public class and methods included in this pull request.
• Migrate all the changes suggested in this wordpress-develop pull request to Gutenberg, including the naming decision. #58383
• Decide the final shape of the bindings object used in the blocks and make the necessary changes: #58337
• Backports to WordPress.
• Add more tests for the bindings, especially in the editor.
• Add validation in the WP_Block_Bindings_Registry class like others like WP_Block_Type_Registry are doing: link.

Fixes/updates for WordPress 6.5 beta 1 (February 13th)

• Review the accessibility of the editor with the accessibility team, including the suggestions made: link.
  • Rich Text: Add aria-readonly attribute to Rich Text component #58687 (review)
• Migrate to Gutenberg the changes made in this core pull request: link. PR: #58683
• Fix a bug with strcasecmp reported here.
• Decide if we should add a WP_Block_Binding_Source class and handle validation there: link. PR: #6042 / Core changeset: 57562
• Refactoring the processing of block bindings into two steps: link. This would solve this issue with the empty images in pattern overrides. PR: #6059
• Add initial documentation. Core changeset: 57560
• Remove unused setAttributes. PR: #58806
• Lock editing by default when the source used in the bindings is not registered in the client and adapt pattern overrides. PR: #58787

Fixes/updates during beta phase

• Fix the way context is added as discussed here. Core / Gutenberg PR
• Remove unnecessary queryId in context: link. Solved as part of Core / Gutenberg PR
• Create a guide about using block bindings. Discussion: 219. Guide part 1.
• Fix metadata attribute not being preserved after block transforms: link. PR: #59179
• Fix query loop not working as expected in the editor when blocks are bound. PR #59283
• Improve the accessibility of the block bindings:
  • Block Bindings: Pressing Enter from connected block doesn't move focus to the newly created block. #58674
  • Block Bindings: UI components that show connected values should be readonly and not disabled #58673
• Review the use-bindings-attributes hook and improve its implementation. As part of that, we should address link. PR with the refactoring: #58895
• Fix insert button when pressing enter in bound blocks. #59361
• Don't show protected meta fields. PR #59326 / Core ticket #59326
• Dev note covering how extenders can use the block bindings.
• Review the current UX and make further improvements: link.
  • Add visual indicator if a block is connected to block binding source #59185
  • Change default "Connected to a custom field" message in bindings #59434
  • Block Bindings: Remove Block Bindings icon from List View, fixes and CSS updates. #59477

WordPress 6.6 planning

This section will be used to keep track of the issues that could potentially be addressed for WordPress 6.6.

As explained in this comment, the idea is to keep the scope limited and work on more functionalities if there is time at the end of the release cycle.

Initial plan

Keep in mind that this is not set in stone and it might change. The initial idea is to focus on these aspects:

Polish the existing code

• Add hook to check when we should lock controls when bindings exist: link.
• Use RichText identifier to check if we should make it non-editable: link.
• Explore how to abstract the locking of controls: link.
• Remove the filter when a source is unregistered as discussed here.

And work on new aspects like:

• Add the possibility of editing the value of the meta fields directly from the bound blocks.
• Improve the UX when the editing of bound blocks is locked.
• Define and implement UX for editing custom fields directly from blocks connected.
• Add support for more core blocks based on feedback. #59607

Out of scope for 6.6

Trying to keep the scope limited for this short release, the idea is to work on these functionalities only once the previous points are finished:

• Add a UI to allow users to add bindings through the Editor.
• Create new sources: Site data, post data, taxonomy data.
• Explore the possibility of creating a filter to modify the value of the meta field returned. Ex: Change the date format with PHP.
• Explore the possibility of concatenating custom fields somehow. Ex: site_url + field_id.
• Explore the possibility of creating "before/after" setting until an Inline Binding functionality is implemented.
• Replace core blocks like Post Author to use variations using these bindings.
• Create opt-in mechanism and expand support for custom blocks (This depends on the HTML API supporting any HTML tag).
• Change the UI to use the upcoming DataViews: link.
• Probably using DataViews, add the possibility of creating new custom fields.

[SantosGuillamot]

Initial experimental MVP

We can start with a simple experimental version, that can be activated through Gutenberg → Experiments, to kick off the project. We can aim to just:

• Connect the paragraph content and the image URL through an object in the block attributes. Just by having the following block attribute, it should display the value of the custom field in the frontend:

<!-- wp:paragraph
    { 
        "connections": {
            "attributes": {
                "content": { 
                    "source": "meta_fields",
                    "value": "my_custom_field"
                }
            }
        }
    }
-->

Keep in mind that this is just an example, and we have to discuss how the API should look. Additionally, it might require adding support for these connections in the block itself.

• Have a really basic UI to add those connections and select the custom field we want to connect.

For this first experimental MVP, I would leave out of the scope:

• Don’t support reading/writing of the custom field values from the editor: We wouldn’t be able to read the value of the custom field or update its value from the editor. We could use a placeholder in the editor (in the frontend it should show properly). Making it work in the editor is trickier, and we might hit some blockers that can be solved in next iterations.

• Don’t show a list of available custom fields: For the same reason, I propose using a text input and keeping the user responsible that it matches an existing custom field in this initial phase.

[Mamaduka]

By the way, the meta attributes source was only deprecated in WP 5.4, and core still maintains backward compatibility.

I wasn't actively involved in the project then, so I don't remember the reason for the deprecation. We should probably dig up old PRs and check.

[SantosGuillamot]

I wasn't actively involved in the project then, so I don't remember the reason for the deprecation. We should probably dig up old PRs and check.

Thanks a lot for sharing! 🙂 I've been taking a look at the old PRs and it seems the deprecation was added in this pull request: link. I've been reading the different conversations and, as stated in the Dev Notes, it seems it was deprecated in favor of the EntityProvider. Which is supposed to "provide a more flexible and powerful way for building blocks that source data from different properties of WordPress entities and data." But I wasn't involved in the project either, and I couldn't find too much information, so I might be missing something.

Anyways, I believe the case here is slightly different than the meta attributes source. In this case, we want that block attributes that are not usually connected to meta fields, can do it if the user wants. If we take the paragraph content as an example, it uses source: html. In most cases, users will want to use the paragraph block as it is used right now but, if wanted, this would offer the possibility to connect it to a meta field (Post Excerpt for example) through a UI in the editor.

Apart from that, blocks using the old meta source would keep working as well. It's just that those attributes wouldn't have the UI to connect to a different meta field. If we consider this a need, we could explore how to support that too in the future.

[michalczaplinski]

I've opened the PR to allow connecting the url attribute of the Image block to Custom Fields:

• Allow connecting "url" and "title" attributes of the Image block to custom fields. #53488

[gziolo]

By the way, the meta attributes source was only deprecated in WP 5.4, and core still maintains backward compatibility.

@mcsf should be the best person to contact, in case you need to know the details. Here is the initial implementation #2740.

[mcsf]

It's been a long time and my memory is fuzzy, but I believe the original meta source was deprecated due to a combination of:

• Gutenberg betting on and consolidating its data needs around Entities as introduced in 2019
• suboptimal performance and/or ergonomics of the meta source compared to normal attributes
• general lack of interest for post meta as an attribute source (newcomers were likely to not use them, whereas heavy users of meta were likely to not use the block editor) weighed against the cost of maintaining that specific source, which IIRC was a bit shoehorned into parts of the block API

[youknowriad]

I think the main problem of the meta source compared to this new proposal is that it requires folks to actually write a new block by explicitly marking a given attribute as a "meta" attribute. While this new proposal allows setting the source as an attribute of existing blocks (no need to write new blocks).

[glendaviesnz]

@SantosGuillamot, @Poliuk I have added a tracking issue for partial syncing, which is going to have some overlap with this work.