Block Bindings: Open the stable editor APIs #65713
Conversation
SantosGuillamot
requested review from
gziolo,
artemiomorales and
cbravobernal
SantosGuillamot
added
[Type] New API
SantosGuillamot
changed the title
| // Only open this API in Gutenberg and for `core/post-meta` for the moment. | ||
| let getFieldsList; | ||
| if ( globalThis.IS_GUTENBERG_PLUGIN ) { | ||
| getFieldsList = action.getFieldsList; | ||
| } else if ( action.name === 'core/post-meta' ) { | ||
| getFieldsList = action.getFieldsList; | ||
| } |
There was a problem hiding this comment.
@gziolo Could you confirm this is the proper way to enable the API for Gutenberg but keep it private for WordPress 6.7?
PD: I had to split the conditional this way because the linter was complaining that globalThis.IS_GUTENBERG_PLUGIN can't be used among other checks.
There was a problem hiding this comment.
Yes, that looks right. In effect, all custom sources can test getFieldsList with the Gutenberg plugin, but only core/post-meta is handled with WP core.
|
Size Change: -85 B (0%) Total Size: 1.77 MB
ℹ️ View Unchanged
|
SantosGuillamot
added
the
Needs Dev Note
SantosGuillamot
requested review from
ellatrix,
ntwb,
nerrad,
ajitbohra and
tellthemachines
as code owners
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
SantosGuillamot
added
the
Backport to WP 6.7 Beta/RC
| // Only open this API in Gutenberg and for `core/post-meta` for the moment. | ||
| let getFieldsList; | ||
| if ( globalThis.IS_GUTENBERG_PLUGIN ) { | ||
| getFieldsList = action.getFieldsList; | ||
| } else if ( action.name === 'core/post-meta' ) { | ||
| getFieldsList = action.getFieldsList; | ||
| } |
There was a problem hiding this comment.
Yes, that looks right. In effect, all custom sources can test getFieldsList with the Gutenberg plugin, but only core/post-meta is handled with WP core.
packages/blocks/README.md
Outdated
| @@ -793,6 +843,22 @@ _Returns_ | |||
|
|
|||
| - `Array`: Updated Block list. | |||
|
|
|||
| ### unregisterBlockBindingsSource | |||
|
|
|||
| Unregisters a block bindings source | |||
There was a problem hiding this comment.
Nit: this could provide more details.
| Unregisters a block bindings source | |
| Unregisters a block bindings source by providing its name. |
|
|
||
| _Parameters_ | ||
|
|
||
| - _source_ `Object`: Properties of the source to be registered. |
There was a problem hiding this comment.
Are all of the properties mandatory?
There was a problem hiding this comment.
No, they are not. I wrapped the optional ones with [] because I thought that was the way to do it. Should I clarify it in the description anyway?
There was a problem hiding this comment.
Ah, I missed that nuance. I would welcome the update to the description of the parameters to make it easier to discover that some params are optional.
There was a problem hiding this comment.
Added in this commit: a5792ef
There was a problem hiding this comment.
Overall, the API is in a very good state, in my opinion. It's very late in the WP 6.7 cycle so I'm not sure whether landing it before WordPress 6.7 beta 1 is still doable. This would have to be confirmed and handled by @noisysocks and @kevin940726.
I left mostly comments about improvements to how the API is documented, which could use a more comprehensive check separately.
SantosGuillamot
force-pushed
the
update/open-stable-block-bindings-apis
branch
from
212b8c8 to
1fbfde4
Compare
|
Ignore the above, I've cherry-picked into |
|
Awesome, thank you so much @noisysocks. Great job @SantosGuillamot and @cbravobernal. Is there a tracking issue for the new reference page for Block Bindings? It’s going to be important to highlight that the server API is available from WordPress 6.5, but the client counterparts need WordPress 6.7. One more thought, for the sake of documentation, I’m wondering if |
Do you mean in the docs? Maybe @justintadlock can help here. In the short term, I want to post an update with these changes in the iteration issue and we have to work on the dev notes in the coming weeks.
It makes sense to me. At least for this particular case. |
Yes, the documentation that explains how to use everything, some existing references: Sure, @justintadlock can help. However, the implementers usually draft the initial version as they have all the necessary insights. Edit: Filed an issue: |
Totally. I just didn't know what was the best place to write down that information. |
* Try use select and dispatch instead of registry * Fix `setValues` * Open `useBlockBindingsUtils` * Open registration APIs * Restrict `getFieldsList` API * Update `useBlockBindingsUtils` docs * Update register/unregister bindings docs * Simplify API functions examples Co-authored-by: Greg Ziółkowski <[email protected]> * Update docs * Update comments --------- Co-authored-by: Carlos Bravo <[email protected]> Co-authored-by: Greg Ziółkowski <[email protected]> Co-authored-by: cbravobernal <[email protected]> Co-authored-by: SantosGuillamot <[email protected]> Co-authored-by: gziolo <[email protected]>
* Try use select and dispatch instead of registry * Fix `setValues` * Open `useBlockBindingsUtils` * Open registration APIs * Restrict `getFieldsList` API * Update `useBlockBindingsUtils` docs * Update register/unregister bindings docs * Simplify API functions examples Co-authored-by: Greg Ziółkowski <[email protected]> * Update docs * Update comments --------- Co-authored-by: Carlos Bravo <[email protected]> Co-authored-by: Greg Ziółkowski <[email protected]> Co-authored-by: cbravobernal <[email protected]> Co-authored-by: SantosGuillamot <[email protected]> Co-authored-by: gziolo <[email protected]>
This reverts commit bbe768c.
* Try use select and dispatch instead of registry * Fix `setValues` * Open `useBlockBindingsUtils` * Open registration APIs * Restrict `getFieldsList` API * Update `useBlockBindingsUtils` docs * Update register/unregister bindings docs * Simplify API functions examples Co-authored-by: Greg Ziółkowski <[email protected]> * Update docs * Update comments --------- Co-authored-by: Carlos Bravo <[email protected]> Co-authored-by: Greg Ziółkowski <[email protected]> Co-authored-by: cbravobernal <[email protected]> Co-authored-by: SantosGuillamot <[email protected]> Co-authored-by: gziolo <[email protected]>
|
@SantosGuillamot I know I'm missing something here and I think I'm probably using the wrong hook to register my script, but I wanted to test the All of my code is here: https://github.com/colorful-tones/wp-testing-plugin I'm registering a custom source here, which works fine: https://github.com/colorful-tones/wp-testing-plugin/blob/main/inc/block-bindings-6-7.php#L77-L83 Then, I'm using And here is the final JavaScript to unregister the source, which does not work: Any guidance you might have is appreciated. Thanks! |
|
Your code looks good to me. Let me try to clarify what is happening:
The problem is that your script is running BEFORE the bootstrap, so the source doesn't exist in the client yet. If you run the exact same code in the console, it should work. Having said that, I'm not sure what is the best way to fix that. I assume it could be solved by using something like |
|
@SantosGuillamot @colorful-tones I think the only real way to get arround those timing issues is to ensure the scripts load in the correct oder. So in this case here the JS file is enqueued with only the Because of that it loads before the There are two ways to get around that.
|
This did the trick. Although, I'm not sure the JS warning in console is sufficient for an end user? Perhaps I'm misunderstanding the use case of these registration/unregistration functions? 🤔 
|
I am not sure if it is a problem for the end user or for the developer. The end user doesn't get a warning because when the source is not unregistered, the source is actually valid. If a block is connected to an invalid source, it should show a warning in the Attributes panel.
The warning is intended for the developer calling |
Ok, this makes sense and answers my initial concern. 👍
Love this, and thanks for clarifying and I'm glad that warning is there for this purpose. 👍 |
|
I drafted a prototype #65921 that potentially could resolve the issue with unregistering sources, and offer a general way for running 3rd party code that might depend on what core, plugins and themes might register by replicating @SantosGuillamot, I noticed that the Block Bindings aren't integrated with other editor screens outside of the site and post editor: |
I've started this pull request to register sources in those screens. Although right now it is really difficult to create bindings there because the UI is not supported for custom sources, post meta fields are not available, and it seems I can't access the code editor. Anyway, it is good to have it there to ensure they are available once the UI is open for more sources. |
This PR is built on top of #65710 because it shouldn't be merged until that one is done.
What?
In this pull request, I propose opening the block bindings editor APIs that I personally consider stable because they have been used privately for a whole release cycle now. This covers:
Block bindings utils
It exposes a
useBlockBindingsUtilshook that returns the helpers to modify themetadata.bindingsattribute. Right now, it includes:updateBlockBindings: This works similarly toupdateBlockAttributes. It can be used to create/remove specific connections.removeAllBlockBindings: This is used to remove all connections existing in a block.These utils are being used by the UI to connect to post meta and by pattern overrides. They can be helpful to let other sources build their own UI if wanted.
Registration API
It exposes the following functions:
registerBlockBindingsSource: to register a source in the client (more on this later).unregisterBlockBindingsSource: to unregister an existing source.getBlockBindingsSource: to get a specific registered source and its properties.getBlockBindingsSources: to get all the registered sources in the client.They are based on other registration APIs like block types, block variations, or block collections.
Source properties
Each registered source in the client can include the following properties:
name: The unique and machine-readable name.label: Human-readable label.usesContext: Array of context needed by the source only in the editor.getValues: Function to get the values from the source. It receivesselect,context, and the blockbindingscreated for that specific source. It must return an object withattribute: value. Similar togetBlockAttributes.setValues: Function to update multiple values connected to the source. It receivesselect,dispatch,context, and the blockbindingscreated for that specific source, including the new value. Similar toupdateBlockAttributes.canUserEditValue: Function to let the editor know if the block attribute connected should be editable or not. It receivesselect,context, and the source arguments.They all include proper testing, and there are JSDocs, but they need to be documented better.
Apart from that, there is the
getFieldsListproperty that remains private for 6.7 and only works forcore/post-metaBUT it is open if Gutenberg is active. This one is not mature enough and this way, it will allow us to gather feedback and iterate on it safely.Why?
Opening the editor APIs was a common demand for block bindings and it empowers what extenders can build with it. Additionally, I believe the APIs we are exposing should be safe.
How?
unlockwhere these functions were called.getFieldsListcan only be used for post meta or when Gutenberg plugin is active.Testing Instructions
These APIs are covered in the block-bindings tests. So they should pass.