Tracking issue: Block bindings API

[SantosGuillamot]

Part of #41236 overview issue. Originally proposed at #51373.

Before this issue, the project was mainly discussed and implemented here.

---

This tracking issue is meant to be used to discuss the strategy of the Block Bindings API. The implementation details or APIs should be discussed in their relevant issues.

It also includes a complete list of related tasks. The idea is to create different iteration issues (for each WordPress release, for example) and handle them progressively.

We'll post updates each time a new iteration is created or finished. You can subscribe to the different iterations for more regular updates.

---

Goal of the block bindings API

This API aims to connect block attributes to values, obtained from different sources, that might vary depending on the context. For example, a value like post_author that changes depending on the current post.

This will expand the capabilities of existing blocks without the need to create new ones, which will empower theme developers and site owners. For example, having a heading block with the content of the Post Author without needing a new Post Author block.

How the API works

I think it makes sense to differentiate between

Bindings creation

To create a binding of a block attribute and an external source, users should add a "bindings" object in the "metadata" attribute with the relevant information.

"metadata": {
    "bindings": {
        "content": {
            "source": "core/post-meta",
            "args": {
                "key": "custom_field"
            }
        }
    }
}

Each source could have different arguments depending on their needs.

Additionally, the idea is to create a UX that easily adds this object directly thorugh the interface. It must be extendable to cover the different sources' needs.

What happens in the server

If a block has the "bindings" object, there are two steps happening in the server:

1. Get the value from the source defined in the binding.

Using the provided APIs, each source must define how to get the appropriate value. For example, in the case of the meta_fields source, it could use the get_post_meta function, while other sources might need something different.

2. Update the HTML using the value obtained from the source.

Once we have the value from the source, we can update the relevant part of the HTML with the block attribute selectors and the HTML API. For example, if it is bound to the paragraph content, it knows it has to replace the inner content, while if it is linked to the image URL, it knows it has to replace the src attribute.

What happens in the editor

When a "bindings" object is found in a block in the editor, there are two different scenarios:

1. Allow editing of the external source

The idea is to provide the possibility of directly editing the value of the external source through the block interface. This means that, if a paragraph content is connected to a custom field, when you edit the RichText you are actually editing the value of the custom field and not the content of the paragraph.

2. Lock editing

Depending on each source, they might want to lock the editing of the external source and just lock the editing. This could happen when the user is in a template or when they don't have permission to edit the external source, for example.

As each source will have different needs, they should be the ones deciding when to lock it using the provided APIs.

Core sources

As mentioned, apart from providing the mechanism to allow users to create their own sources, there will be some core sources added by default. Some examples of this could be:

• Post meta custom fields.
• Pattern overrides.
• Site data.
• Taxonomy data.

Feel free to suggest other sources that should be considered here.

Supported blocks

The idea is to allow any block to opt-in for the block bindings API and make any block attribute available. However, the server logic relies on the HTML API, which is still a work in progress at the time of this writing. Because of that, we will add support for core blocks progressively until we consider it safe to open it for any block.

These are the block attributes supported so far:

• Paragraph content.
• Heading content.
• Image URL, alt, and title.
• Button URL, text, linktarget, and rel.

Please share any block you consider important and not supported yet.

Resources

These are some resources published that can help to understand the Block Bindings API better:

• Block Bindings API Dev note.
• Introducing Block Bindings, part 1: connecting custom fields.
• Introducing Block Bindings, part 2: Working with custom binding sources.

Roadmap

This is the list of tasks that we currently have in mind for the block bindings API. We will update this list as we progress and learn more about this initiative's needs.

The idea is to create different iteration issues (for each WordPress release, for example) and handle them progressively.

We'll post updates each time a new iteration is created or finished. You can subscribe to the different iterations for more regular updates.

• Bindings creation

• Add UI to create bindings through the interface.
• Add extensibility mechanisms to allow other sources to adapt to their needs.

• Server APIs

• Revisit how sources access the needed context.
• Use set_inner_html for the existing block attributes.
• Remove the filter when a source is unregistered as discussed here.

• Editor APIs

• Improve the existing hook implementation.
  • Block bindings: don't use hooks #60724
• Add support for allowing editing.
  • Block bindings: don't use hooks #60724
• Add callback so sources can decide when to lock/allow editing.
• Define and implement UX for editing custom fields directly from blocks connected.
• Revisit how sources access the needed context.
• Define how to work with placeholders.
• Improve the UX when the editing of bound blocks is locked.
• Explore how to abstract the locking of controls: Features like pattern overrides and block bindings have limited control over block UI #58233.
• Move logic from editor hook to core.
• Explore how theme/plugins can decide when to lock/allow/create bindings.

• Core sources

• Support editing in "Post meta" source.
• Use block bindings editor API to update pattern overrides.
• Add support for "Site data" source.
• Add support for "Taxonomy data" source.

• Supported block attributes

• Add support for more block attributes. Overrides in Sync Patterns: expand block support #59607.
• Add a mechanism to opt-in for bindings in any block.

• Other potential features

• Explore the possibility of adding a default value for bindings: Add __default binding for pattern overrides #60694
• 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.
• Change the UI to use the upcoming DataViews: DataViews component #55083.
• Probably using DataViews, add the possibility of creating new custom fields.

[SantosGuillamot]

I've just created an iteration for WordPress 6.6. These are the tasks that we can expect to work on during this release cycle.

As previously mentioned, the main focus will be to allow editing in the existing core sources.

Bindings creation
Even though we'll probably won't add a UI to create bindings yet, we'd like to start discussing how it should work.

Server APIs

• Revisit how sources access the needed context.

Editor APIs

• Improve the existing hook implementation.
• Add support for allowing editing.
• Revisit how sources access the needed context.
• Define how to work with placeholders.
• Add callback so sources can decide when to lock/allow editing.
• Improve the UX when the editing of bound blocks is locked.
• Define and implement UX for editing custom fields directly from blocks connected.

Core sources

• Support editing in "Post meta" source.
• Use block bindings editor API to update pattern overrides.

[richtabor]

Define how to work with placeholders.

I question if it should be front-and-center within placeholders. Or instead more like overrides, within the "Advanced" panel—at least initially, for selecting a source and key. Could potentially use a modal just like overrides.

I'm a bit cautious of putting something more developer-oriented in such a prominent position within the placeholder. And if we do something like overrides does, we would not need both a UX for placeholder state and for post-placeholder. It could be one experience, across any blocks.

[SantosGuillamot]

Now that WordPress 6.6 is almost here, I've closed the current iteration and opened a new one for 6.7.

WordPress 6.6 update

Most of the functionalities expected for 6.6 landed in time. Among other things, it includes the possibility of editing the value of the custom fields directly from the connected blocks:

new.editing.demo.mp4

You can find a more detailed list of what was included, as well as more demos, in this comment and in the core note.

New iteration for WordPress 6.7

I have just created a new iteration for 6.7, which will be used to share regular updates and track progress. Let's use it for discussing topics related to it.

As explained there, the initial idea is to focus on:

• Follow-ups from 6.6 and bug fixes: There were a few items that weren't included in the 6.6 iteration that will need some work. Additionally, bugs need to be addressed.
• Add UI to connect attributes with the binding sources: Basically, add the first iteration to be able to create the bindings through the UI instead of having to go to the Code Editor.
• Polish and open block bindings editor’s APIs for extenders: Core sources like "Post Meta" use some private APIs to handle bindings in the editor. The idea is to polish those APIs to enable external developers to use them.
• Add support for more core sources: In order to ensure that the editor APIs fit future use cases, it'd be great to add support for more core sources, or at least experiment with them in case we want to create them in the future.
• Support anything needed by pattern overrides: We can expect some work needed to support new functionalities in pattern overrides.

[asafm7]

Is this the place to suggest Block Binding support for the Embed block?

[SantosGuillamot]

There is this related issue where people are sharing what blocks to support for synced pattern overrides and block bindings. It might be good to share your opinion there as well to get a better understanding of which blocks are considered more important and why?

[haszari]

To use block bindings, first you need to define and expose some custom meta fields. Currently this has to be done via PHP. As I understand it, there's no UI in WordPress core to set a custom meta field on a post, that can be bound to a block – is that accurate?

I'm interested in that possibility – allowing users to add custom metadata to posts, and then use that data in block-powered layouts. I'm hoping this is in the core roadmap somewhere.

Does this issue include scope for adding, editing custom meta fields, and exposing/registering so they can be used in blocks? Keen to follow progress, if there's an issue or a roadmap item please link me to it.

[annezazu]

Hey there @haszari! Great questions. The best next place to look is the iteration issue for 6.7 for block bindings. This is a scoped issue for targeted items for the 6.7 release. As part of that check out a recent update from four days ago that includes a demo of a UI to create bindings in the editor itself. . You can expect an iteration issue for each subsequent release going forward to help track and follow progress outside of these larger tracking issues that cover larger bodies of work.

[haszari]

Awesome, thanks @annezazu – will follow along there :)

[haszari]

Polish and open block bindings editor’s APIs for extenders: Core sources like "Post Meta" use some private APIs to handle bindings in the editor. The idea is to polish those APIs to enable external developers to use them.

Clarifying one point – @annezazu does that issue cover adding a UI for adding/editing custom metadata fields (e.g. on a post). The part that I'm confused about is how to set up the source data to bind to.

I had imagined that any custom meta fields would work, and that I'd be able to add arbitrary custom meta to a post using WordPress core only, no plugins or custom code. Is this something that's in the roadmap, for 6.7 or further on?

As I understand it, these block bindings can only use data from custom plugins – if I'm running vanilla WordPress, and want to add an extra field to each post (from UI), how do I do that? I have a vague memory pre-Gutenberg of arbitrary metadata fields in the (old) post editor, is there a replacement for that, or a better way to do it?

[SantosGuillamot]

If I am understanding you correctly, creating custom fields is slightly different and not covered by block bindings. Block bindings connect block attributes and dynamic sources, including custom fields. However, how those custom fields are created is a different topic, and it feels a bit more complex.

Right now, new custom fields are dynamically registered during the server processing. You need to have a PHP function running register_post_meta. In the future, WordPress might include a UI for that, maybe using Data Views, but it could get tricky. Once the proper mechanisms are in place, we might want to explore reusing them as well in the block bindings UI somehow, but that is a bit unclear to me at this point.

[haszari]

If I am understanding you correctly, creating custom fields is slightly different and not covered by block bindings. Block bindings connect block attributes and dynamic sources, including custom fields. However, how those custom fields are created is a different topic, and it feels a bit more complex.

Exactly – yes, they are separate, but related! I'm keen to help figure out the complexity of registering and editing custom metadata, which would make this whole system much more powerful and amazing!

[SantosGuillamot]

Now that 6.7 is released, let's do a quick recap of what was included there and what can be expected in 6.8.

6.7 release

This is a quick summary copied from this comment. For a detailed explanation of the changes you can check the 6.7 Dev Note.

User interface (UI) to connect blocks and custom fields

This is specific to post meta fields as the APIs to extend this UI weren’t considered stable yet. Other sources won't be able to use it in 6.7.

This release comes with a new UI that allows users to connect attributes with custom fields, making it possible to create bindings through the UI instead of the Code Editor. In the following demo, I create a template from scratch connecting blocks to movie meta fields and show how it is reflected in the frontend.

Demo.block.bindings.-.template.mp4

As shown in the video, it uses the default values when editing a template and, if it doesn't exist, it uses the meta label. Also as part of this release, a new label argument has been included in register_meta to be able to consume human-readable text instead of the key.

Open stable editor APIs

During 6.6, there were some existing APIs to show and update the connected values that remained private but were being used internally in "post meta" and "pattern overrides". In 6.7, it has been decided to open the ones considered stable so other extenders can benefit from them. The APIs exposed are part of the dev note.

Plans for 6.8

I have just created a new iteration issue for 6.8, which will be used to share regular updates and track progress. Let's use it to discuss topics related to it.

As explained there, the initial idea is to focus on:

• Improve the UI and make it extensible: Right now, the UI to create bindings is only available post meta. The idea is to polish it and explore using DataViews, which comes with some benefits, and figure out the proper APIs to let other sources hook into this.
• Create mechanisms to support more blocks: As explained in this issue, there are a few limitations that need to be solved before allowing more blocks to use block bindings. Not all the limitations apply to all blocks, so the idea is to approach it progressively. For example, dynamic blocks only need the attributes locking and the opt-in mechanism solved. Or it can support basic CSS selectors as a first step for static blocks.