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