-
Notifications
You must be signed in to change notification settings - Fork 4.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Block Bindings: Docs API reference. #66251
base: trunk
Are you sure you want to change the base?
Conversation
Flaky tests detected in 86a9902. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/11486445656
|
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. |
472ee5a
to
0cb8c9d
Compare
- `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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since getFieldsList
can in fact be used by third-party developers, should we say something like the following instead?
getFieldsList
is an experimentalfunction
that 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think you mean to set wpMoviesVisualizationDate
rather than return here, otherwise the variable is always undefined.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion:
Once a source is registered, any supporting block's
metadata.bindings
attribute 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We could try removing "is" to make this cleaner.
name
:string
that sets the unique ID for the custom source.args
:array
that contains:label
:string
with the human-readable name of the custom source.uses_context
:array
with the block context that is passed to the callback (optional).get_value_callback
:function
that will run on the bound block's render function. It accepts three arguments:source_args
,block_instance
andattribute_name
. This value can be overridden with the filterblock_bindings_source_value
.
What?
Initial draft for Block Bindings
Why?
Documentation is necessary.