Block Bindings: Docs API reference. #66251
Conversation
cbravobernal
added
the
[Type] Developer Documentation
|
Flaky tests detected in 86a9902. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/11486445656
|
cbravobernal
requested review from
ajitbohra,
juanmaguitar,
fabiankaegy and
ndiego
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. |
cbravobernal
force-pushed
the
docs/block-bindings-first-docs
branch
from
472ee5a
to
0cb8c9d
Compare
gziolo
requested review from
justintadlock,
artemiomorales and
SantosGuillamot
| - `getValues` is a `function` that retrieves the values from the source. (optional) | ||
| - `setValues` is a `function` that allows updating the values connected to the source. (optional) | ||
| - `canUserEditValue` is a `function` to determine if the user can edit the value. The user won't be able to edit by default. (optional) | ||
| - `getFieldsList` is a private `function`. It cannot be used yet by third-party developers. It creates a list for the block bindings UI with post meta. |
There was a problem hiding this comment.
Since getFieldsList can in fact be used by third-party developers, should we say something like the following instead?
getFieldsListis an experimentalfunctionthat should not be used yet by third-party developers in production, as it is subject to change and may be removed in upcoming releases. It creates a list for the block bindings UI with post meta.
| return getEditedEntityRecord( | ||
| 'postType', | ||
| context?.postType, | ||
| context?.postId | ||
| ).meta?.wp_movies_visualization_date; |
There was a problem hiding this comment.
I think you mean to set wpMoviesVisualizationDate rather than return here, otherwise the variable is always undefined.
There was a problem hiding this comment.
I found a few typos; I'll push a commit to fix those and left a few other suggestions.
One thing: The parameter definitions throughout the document are inconsistent and repeat themselves unnecessarily. I suggest revising the definitions like in this comment using either colons (:) or hyphens (-) between the property name and its description to make these easier to read.
|
|
||
| ## Compatible blocks and their attributes | ||
|
|
||
| Right now, not all block attributes are compatible with block bindings. There is some effort going on increasing this compatibility, but for now, this is the list: |
There was a problem hiding this comment.
Suggestion:
This is some ongoing effort to increase this compatibility...
|
|
||
| Registering a source requires defining at least `name` and a `callback` function that gets a value from the source and passes it back to a block attribute. | ||
|
|
||
| Once a source is registered, any block that supports the Block Bindings API can use a value from that source by setting its `metadata.bindings` attribute to a value that refers to the source. |
There was a problem hiding this comment.
Suggestion:
Once a source is registered, any supporting block's
metadata.bindingsattribute can be configured to read a value from that source.
| - `name` is a `string` that sets the unique ID for the custom source. | ||
| - `args` is an `array` that contains: | ||
| - `label` is a `string` with the human-readable name of the custom source. | ||
| - `uses_context` is an `array` with the block context that is passed to the callback (optional). | ||
| - `get_value_callback` is the `function` that will run on the bound block render function. It accepts three arguments: `source_args`, `block_instance` and `attribute_name`. This value can be overriden with the filter `block_bindings_source_value`. |
There was a problem hiding this comment.
We could try removing "is" to make this cleaner.
name:stringthat sets the unique ID for the custom source.args:arraythat contains:label:stringwith the human-readable name of the custom source.uses_context:arraywith the block context that is passed to the callback (optional).get_value_callback:functionthat will run on the bound block's render function. It accepts three arguments:source_args,block_instanceandattribute_name. This value can be overridden with the filterblock_bindings_source_value.
What?
Initial draft for Block Bindings
Why?
Documentation is necessary.