Block Bindings iteration for WordPress 6.7

[SantosGuillamot]

Iteration of the Block bindings API tracking issue.

This issue will be used to gather the new functionalities and bug fixes expected to be included in WordPress 6.7. It will serve to share regular updates and progress.

Please keep in mind that the list of issues will change once new ones come up.

For this iteration of WordPress 6.7, the focus will be on these items (no specific order):

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

EDIT: I created a new section for "Saving workflows" after the issues raised and because it seems a big topic to be discussed.

Follow-ups and bug fixes

• Don't show post meta fields that start with an underscore. (Temporary fix)
• Fix empty custom fields not being editable in bindings.
• Add warning when block attribute is connected to an invalid source.
• Rely on Text component instead of Truncate in bindings panel.
• Can't save changes to the source if custom fields are opened
• Potential filter to modify the value returned by bindings.
• Improve accessibility of bound paragraphs when using a screenreader in Navigation Mode.
• Prioritize existing placeholder over bindingsPlaceholder.
• Change "This block is connected" indicator to make it accessible.

Nice to have

• Add indicator that an attribute is connected instead of hiding the controls.
• Add support for image caption.
• Add support for image href.
• Ensure custom field changes work fine with revisions.
• Send only edited values to the POST API requrest

UI to create bindings

For more info about the tasks, most of the discussions happened here.

• Create initial UI for connecting block attributes and custom fields.
• Block Bindings: Fix long keys overflow in bindings panel.
• Create utils to add/remove bindings in the object that can be reused.
• Decide where the bindings panel should live and in which cases it should be available: link.
• Remove experimental flag once the UI is considered ready.
• Add label argument to register meta.
• Add support for connecting custom fields in templates.
• Use post meta label from register_meta in block bindings workflows.
• Explore how permissions should work with bindings creation: link.

Nice to have

• Abstract the useToolsPanelDropdownMenuProps util.
• Add backdrop-color to connected blocks.
• Keep iterating on the UI:
  • Add a "Clear" button? See link.
  • Add a search bar?
  • Add a prompt when the connection hasn't been created yet. See link.
  • Improve UI of "read-only" panel. See link.

Polish and open editor APIs

• Improve the way sources are registered: This includes a refactoring to work as blockTypes, blockVariations, blockCollections... It also includes new functions like unregisterBlockBindingsSource and unit tests.
• Use @wordpress/warning during block registration instead of console.error and console.warn.
• Unify getValue/getValues and setValue/setValues APIs.
• Don't provide default canUserEditValue in reducer.
• Bootstrap sources defined in the server.
• Improve how the context is handled in the editor.
• Improve how the context is handled in the server.
• Allow bindings bootstrap after registration.
• How should bindings handle placeholder/fallback values?
  • Change placeholder when attribute is bound.
  • Remove getPlaceholder API and rely on key argument or source label.
• Revisit the extensibility mechanism to allow other sources to appear in the UI. See link.
• Add docs and types to source registration.
• Make the editor APIs public.

Support for more core sources

Nice to have

• Create an experiment to support taxonomy meta and decide if it should be included as a core source.
• Create an experiment to support site data and decide if it should be included as a core source.
• Create an experiment to support post data and decide if it should be included as a core source.

Saving workflows

Nice to have

It isn't still clear if saving workflows should be modified or not as discussed here.

• Editing bound paragraph in post editor causes "Site Updated" message to appear.
• How/if to improve save workflows to notify users of specific post data changes?.
• Output granular post meta changes in a list.
• Add indicator for modified post meta in pre-publish flow

Backports

• Bootstrap sources defined in the server.

[fabiankaegy]

@SantosGuillamot Thank you for creating this new iteration issue :)

Do you think it is feasible as part of 6.7 to aim for opening up the block bindings features (and therefore block pattern overrides) to 3rd party blocks / extenders?

[SantosGuillamot]

Do you think it is feasible as part of 6.7 to aim for opening up the block bindings features (and therefore block pattern overrides) to 3rd party blocks / extenders?

I'm afraid it will probably take more time than this release. To give more context, block bindings heavily rely on the HTML API, which still lacks a few functionalities to safely interact and modify any HTML element. It needs to ensure that it doesn't create any security issues or break the page. For core blocks where the markup is controlled, this isn't a big problem, but opening it for any 3rd party block, which could have any markup, could trigger unexpected issues. Additionally, a new opt-in mechanism would need to be defined.

Hopefully, if I am not mistaken, the HTML API is not far from being able to handle these use cases, so I believe it should probably be one of the top priorities for upcoming releases.

In the meantime, if there is a need to support other core blocks, those could be considered.

[SantosGuillamot]

I've opened a couple of pull requests/discussion that will affect the editor public APIs in case anyone wants to share feedback:

• Block Bindings: Unify getValue/getValues and setValue/setValues APIs #63185.
• Block Bindings: Improve the way block bindings sources are registered #63117.

[gziolo]

Thank you for opening the iteration for WordPress 6.7.

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.

That sounds like a potential key highlight in the release. It was one of the most anticipated features so far based on the feedback received. In particular, it will be interesting in conjunction with the Pattern Overrides design interface.

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.

This is another key aspect of opening the counterpart for the server-side API exposed in WordPress 6.5. It will also require some glue layer to pass some data from the server to the client to represent better custom sources that get registered only on the server in the UI.

[SantosGuillamot]

Update

There have been three main areas of work during the last weeks

UI to create bindings

The issue to discuss the potential workflows is receiving a lot of feedback, which is amazing 👏

The idea is to try to approach it progressively. Start with a basic version and keep iterating on top of that. That way, it adds value and let us test as soon as possible, which should help with the discussion.

We have started working on an initial prototype in this pull request, which is not far from ready.

Polish editor APIs

There have been a bunch of pull requests going on to polish the editor APIs in order to make them ready to be opened. I feel confident that it is on good track and it is a matter of making some decisions and review the existing code.

So far, these are the things that need to be solved before making them public:

• Improve the way sources are registered: This includes a refactoring to work as blockTypes, blockVariations, blockCollections... It also includes new functions like unregisterBlockBindingsSource and unit tests.
• Bootstrap sources defined in the server: Gutenberg PR and Core backport.
• Unify getValue/getValues and setValue/setValues APIs.
• Revisit how bindings should handle placeholders.
• Add docs and types to source registration.

Most of them seems to be working. Once they are merged, I feel the APIs could be open in Gutenberg.

Additionally, we have been working on:

• Improve how the context is handled: In the editor and in the server.

This one is not strictly needed to open the APIs, but I consider it important, and it seems to be working.

Saving workflows

While working on improving the saving workflows for post meta ((granular post meta changes and fixing/refactoring the logic for the “Site Updated” message), some important issues where raised that made us revert the current behavior in this pull request.

For that reason, we decided to take one step back and open a new issue to gather all the context to ensure we make informed decisions and avoid more issues like these ones in the future.

• How/if to improve save workflows to notify users of specific post data changes?  #63425

The idea is to discuss there how the saving workflows should work and split it into smaller tasks once it is clearer. It'd be great to get more thoughts there.

Next steps

These are what I considered that could be the next steps for the upcoming weeks:

• Keep the discussion and the prototype around the UI going.
• Review and make decisions around the editor APIs to start merging the changes progressively.
• Solve the remaining issues listed in the opening post, especially the bugs.
• Foster the discussion around saving workflows.

We could also start working on experimenting with potential future core sources to ensure the editor APIs fit their use case. Although we must be aware that the editor APIs are likely going to change in the mentioned PRs.

[bacoords]

Would love to see if this is feasible: #63763

[SantosGuillamot]

Would love to see if this is feasible: #63763

Personally, I would prefer to focus on the internals and add support for more core blocks once the right abstractions are in place and "hardcoding" is not needed. But I'm happy to help, review, or guide if this is wanted for pattern overrides and someone plans to work on that.

[SantosGuillamot]

Update

UI to create bindings

The first prototype of the UI to connect block attributes and custom fields has been merged. In the end, it was included under an experimental flag because there are some uncertainties that have been added as follow-ups to the list.

352084865-a366cf1e-035f-48ed-b70c-addb78fdd520.mp4

The main aspect before removing the experimental flag is deciding where this panel should live, which isn't still clear because it might change the workflows of the paragraph and heading blocks, which are widely used.

Apart from that, we have to figure out how to make it work in templates, explore how to let external sources hook into this, and keep iterating on the UI.

Editor APIs

The editor APIs are shaping nicely and most of the tasks to be able to open them have been addressed:

• Improve the way sources are registered.
• Unify getValue/getValues and setValue/setValues APIs.
• Bootstrap sources defined in the server: Gutenberg and Core.
• Improve how the context is handled in the editor.
• Improve how the context is handled in the server.

There are three main topics remaining:

• Add docs and types.
• How should bindings handle placeholder/fallback values?.
• Revisit the extensibility mechanism to allow other sources to appear in the UI. See link.

Saving workflows

So far, the feedback seems to agree on not changing the saving workflows at all.

Next steps

These are what I considered top priorities for the upcoming weeks:

1. Decide where the UI panel for connecting sources should be placed and implement the necessary changes. More context can be found here and here.
2. Explore how to integrate the UI for connecting sources properly with templates: link.
3. Split the placeholder/fallback for connected attributes discussion into smaller actionable items: link.
4. Add docs and types to editor APIs and open them for usage by plugin authors.
5. Solve the remaining issues listed in the opening post, especially the bugs.

[jhmonroe]

Perhaps this flyout should be handled more the way Preferences modal works, and more like they are proposing here (#62703) for Allowed Blocks UI? More of a common/native experience than a new flyout that isn't used anywhere else? Also a flyout won't allow as much space for scrolling if the list becomes long. Also to more efficiently share code that is used elsewhere when Core devs build a design out

[SantosGuillamot]

Thanks a lot for the feedback. I can see @jasmussen has answered you in the other issue 🙂 As mentioned, it is used in many places across settings/styles in the inspector controls. Actually, it is reusing the same design/components.

Having said that, I believe we can iterate on the design once the workflows are clearer and we know better if a modal fits better.

[SantosGuillamot]

Update

UI to create bindings

Two main topics are being discussed at this point:

• Be able to create bindings in templates: This is tricky because it is hard to identify which post type each template corresponds to. So far, the pull request relies on the slug and exposes a new field in the types endpoint, but it needs to be discussed.
• Decide where the bindings panel should live and in which cases it should be available: It is still not clear how this should work. I opened a proposal to use "Preferences" to let users enable/disable the UI to create bindings, and different alternatives are being discussed there: link.

Editor APIs

Before opening the editor APIs, we need to clarify first how to handle the placeholders and whether they require an API or not. In this comment, I proposed a potential path forward that seems simple and lets us iterate on top of it, although there are a couple of concerns about it.

Code Quality & Bug fixes

• Block Bindings: Create utils to update or remove bindings #64102
• Reuse useToolsPanelDropdownMenuProps util #64105 : Needs follow up PR.
• Can't save changes to the source if custom fields are opened: There is a proposal to fix this, but it needs to be discussed. Synchronizing legacy meta boxes and the React store changes is tricky.
• Block Bindings: Fix long keys overflow in bindings panel #64465

Next steps

These are what I considered top priorities for the upcoming weeks:

• Review the approach and merge the pull request to create bindings in templates: link.
• Review the approach and merge the pull request to make the UI to create bindings work the same way as "Advanced" control and add a preference to enable it: link.
• If there are no blockers or concerns around the suggested approach for placeholders, address the tasks indicated in the discussion: link. There are a few tasks that can be handled regardless of the decision taken because they are bug fixes.
• Review and merge the code quality and bug fixes open pull requests.
  • Block Bindings: Create utils to update or remove bindings #64102
  • Reuse useToolsPanelDropdownMenuProps util #64105
  • Fix: Store post meta changes are overridden when custom fields meta box is enabled #64505
• Add docs and types to source registration.

[SantosGuillamot]

Remaining aspects for 6.7

With WordPress 6.7 beta 1 being on October 1st, and the last Gutenberg RC expected for September 25th, I wanted to recap what I consider the most important remaining steps to include in that release. They can seem a lot of things, but most of them are already pretty advanced.

Please let's keep each discussion in its relevant issue or pull request

UI to create and modify bindings - Relevant pull request

In this initial pull request, the UI to create and modify bindings was added as an experiment. However, there were a few challenges we needed to solve before opening it.

In this new pull request, some changes have been made to remove the experiment. Although there are still some aspects being discussed, these are the most relevant changes:

• Create a new "bindings" group that is placed on top of the Advanced settings. This solves the problem we face of creating a new "Settings" tab for blocks like paragraphs of headings.
• It creates a new canUpdateBlockBindings editor setting that is used to enable this or keep the "read-only" panel. By default, only admin users can create and modify bindings.
• Polish the UI and help texts.

Show list of available fields in templates - Relevant pull request

In templates, there is no post ID, so it is tricky to get the meta fields from the API. The mentioned pull request explores the possibility of adding a new meta property to the types endpoint and call this endpoint from the template. Right now, it inherits the post type from the template slug.

Improvements to how placeholders are handled - Relevant issue

In the linked comment, I tried to sum up the current status and the necessary changes. There, I propose using the key as a special argument to simplify the implementation until we figure out what is needed. If we go that path, these would be the missing tasks:

• Fix editing locking when the value is empty.
• Change prompt/placeholder when the value is empty
• Change fallback when the value returned by the source is undefined (in templates, for example).
• Add error message when using a source that is not defined.

Add docs and types to source registration

Docs and types should be added before making the APIs public in order to ensure external sources can easily use them.

Review getFieldsList API

Right now, we are using a getFieldsList callback that let sources decide which fields are shown in the UI to create and modify bindings. I believe it can serve well as a first step for external sources to include their own fields. However, I'd like to review the name and the implementation to ensure it is ready to be public.

Additionally, I'd like to explore the possibility of moving this to the server source registration if we modify the types endpoint to make it work with templates.

Open editor APIs

Once the previous steps are done, it should be possible to open the editor APIs. Both the source registration and the different functions and selectors.

Something we should consider is if useBlockBindingsUtils should receive a clientId as optional as suggested here.

Improved how context is handled in the server - Relevant pull request

This one is supposed to be ready but it is waiting for Gutenberg packages update. Once that is done, it should be rebased and adapted.

Fix editing meta values and custom fields meta boxes bug - Relevant issue

As reported in the issue, editing custom fields of bound blocks is currently broken when the metabox is enabled. There are two possibilities explored to solve this:

• Lock editing in fields in editor if meta fields panel is opened .
• Modify the request to update metaboxes.

The first one is simpler but it only solves the problem for this specific use case, and external sources would need to adapt to this as well. The second one is supposed to solve it for all use cases, but it is unclear if it is a correct approach.

Probably the first approach is fine enough for now.

Filter to modify the value returned by bindings - Relevant pull request

In the linked pull request, it is suggested to include a filter to modify the value returned by bindings. It is missing some tests and docs.

Decide if the bindings should be shown in contentOnly mode - Relevant issue

There, it is being discussed what should be the behavior of the bindings panel when contentOnly mode is enabled. We have to keep in mind that in this other pull request, we plan to limit the possibility of creating and modifying the connections to admin users by default.

Address remaining bugs

Apart from that, there are still a few reported bugs we might want to address, although it's true they could be done during the beta phase.

[SantosGuillamot]

Update

Merged

These are the most relevant pull requests merged during last week for me:

• Remove the experimental flag of the UI to create and modify bindings: That pull request covers some UI improvements to make it ready and make it accessible only for admins by default. It also includes a setting that let site owners change this behavior. This serves as a security measure until it is clearer who should be able to manage them.
• Filter to customize the output of a block bindings source.
• Fix: Can't save changes to the source if custom fields are opened.
• Fix empty custom fields not being editable in bindings.
• Add warning in attributes connected to invalid sources.
• Change placeholder of empty connected values.
• Remove getPlaceholder API and rely on key argument or source label: This simplifies the editor APIs.

Ongoing pull requests and discussions

These are the ongoing pull requests/discussions related to block bindings and the status of them

Support connecting attributes in templates - Pull request

I feel this one is almost ready and it improves a lot the user experience. Being able to connect blocks and custom fields in templates is great. As noted in this comment, there are just a few things to review before merging.

Use default values in connected custom fields in templates - Pull request

On top of the previous pull request, I started this one to discuss if we prefer to show the default values instead of the meta keys when connecting a block with a custom field. To me, the UX looks nicer, but it is something to be discussed.

Pass postType in block context in templates - Pull request

Not directly related to block bindings, but it could help in some of the PRs. I opened the linked pull request to discuss if it would make sense to pass the postType as context in the cases where we can inherit it from the template slug.

Add label argument to register_meta and consume it in bindings UI - Core & Gutenberg

As suggested here, and it has been a recurring request, using the meta key in the bindings UI feels too technical. I started this core pull request suggesting adding a new label property to register_meta and I created this pull request in Gutenberg to consume it in the different places.

To me, it is a great example of how the user experience could be improved and it looks much nicer this way.

The core pull request has already a couple of approvals, so it is just a matter of discussing if it is fine to include the new label argument.

Regarding the Gutenberg pull request, it is supposed to be ready. However, it will require minor modifications after the templates PR, which is the base, is merged. Basically, it needs to merge both PHP filters and resolve conflicts in the post-meta.js file.

Set show_in_rest to true when label is defined - Pull request

Related to the previous point, including a new label attribute opens the possibility of setting show_in_rest to true when it is defined. This has been a recurring complaint in the community as well. I opened the linked pull request and a core ticket to discuss that possibility.

How to define capabilities to manage bindings - Pull request

In that pull request, it is being discussed how the capabilities to manage bindings should work. There are different possibilities to consider.

As part of that, I started a pull request in Gutenberg for compatibility that should match whatever is decided there.

Fix: Improve accessibility of bound blocks when using a screenreader - Pull request

There is some discussion around the best approach to address this and if it should be abstracted to any block or just paragraph and heading.

Respect placeholder provided on the server

As discussed here, we might want to explore the possibility of respecting the placeholder provided by the server instead of replacing it with the bindingsPlaceholder.

Potentially improved the read-only panel - Pull request

In the linked pull request, it is being discussed if the read-only panel deserves some special styles, and what, or if we should wait until people start using it and we receive feedback.

---

Apart from that, there are still a few other things to keep in mind:

• Improved how context is handled in the server - Block Bindings: Add context needed by block bindings sources during its processing wordpress-develop#6456. Once the packages sync is done, it will require some adjustments and commit.
• Keep addressing the opened bugs.
• Keep polishing the UX/UI.
• Decide if the bindings should be shown in contentOnly mode - Block Bindings API/UI: Attributes Panel still shows when block is set to 'contentOnly' editing mode. #64731.
• Explore if we need to add more docs and types to editor APIs.
• Review getFieldsList API.
• Open editor APIs once we consider them ready.