Block Bindings: Open the stable editor APIs #65713
Merged
+199
−63
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
SantosGuillamot
requested review from
gziolo,
artemiomorales and
cbravobernal
SantosGuillamot
added
[Type] New API
SantosGuillamot
changed the title
SantosGuillamot
commented
Sep 28, 2024
Comment on lines
+396
to
+402
| // 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
gziolo
reviewed
Sep 30, 2024
Comment on lines
+396
to
+402
| // 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.
gziolo
reviewed
Sep 30, 2024
gziolo
reviewed
Sep 30, 2024
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.
Suggested change
| Unregisters a block bindings source | |
| Unregisters a block bindings source by providing its name. |
gziolo
reviewed
Sep 30, 2024
|
|
||
| _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
gziolo
reviewed
Sep 30, 2024
gziolo
reviewed
Sep 30, 2024
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
|
There was a conflict while trying to cherry-pick the commit to the wp/6.7 branch. Please resolve the conflict manually and create a PR to the wp/6.7 branch. PRs to wp/6.7 are similar to PRs to trunk, but you should base your PR on the wp/6.7 branch instead of trunk. |
noisysocks
pushed a commit
that referenced
this pull request
Oct 1, 2024
* 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]>
noisysocks
added
Backported to WP Core
|
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 |
61 tasks
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. |
getdave
pushed a commit
that referenced
this pull request
Oct 1, 2024
* 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]>
huubl
pushed a commit
to huubl/gutenberg
that referenced
this pull request
Oct 2, 2024
* 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]>
huubl
added a commit
to huubl/gutenberg
that referenced
this pull request
Oct 2, 2024
This reverts commit bbe768c.
draganescu
pushed a commit
that referenced
this pull request
Oct 2, 2024
* 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. 👍 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.