The WordPress coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
Found a bugbugA bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.?Create a ticket in the bug tracker.
WordPress 6.7 introduces various improvements to the BlockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Bindings APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and the built-in post metaMetaMeta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. source, including a default UIUIUser interface and the beginnings of a public editor API.
For an introduction to Block Bindings, first introduced in WordPress 6.5, see the prior dev note.
New Block Bindings UI
Compatible blocks — which currently include Heading, Paragraph, Image, and Button — have received a new default UI for viewing bindings.
Called Attributes, you can find the new tool panel in block settings whenever a compatible block is selected in either the post or site editor.
The panel shows active bindings on the current block. If there are any post meta available, the panel is also interactive, allowing you to bind attributes to those custom fields via the built-in post meta block bindings source.
Currently, there are two limitations to the panel:
It will not allow users to bind attributes to custom sources just yet.
Bindings to custom sources, which can be added via the code editor or other programmatic means, will still display in the panel — they just can’t be connected via the UI for the moment in WordPress 6.7.
A flexible API for connecting custom sources to the Attributes panel is currently under development and is planned for public release in the future.
For now, the rollout of that API has started with the built-in post meta source to allow time for gathering feedback.
For each attribute, the panel will only show custom fields that match its data type. For example, an attribute of type string or rich-text can only be connected to a custom fieldCustom FieldCustom Field, also referred to as post meta, is a feature in WordPress. It allows users to add additional information when writing a post, eg contributors’ names, auth. WordPress stores this information as metadata. Users can display this meta data by using template tags in their WordPress themes. of type string, and an attribute of number can only be connected to another number.
New Post Meta Label Attribute
To improve how custom fields appear in the editor UI, a new label attribute has been created for post meta, which can be defined during registration:
If specified, the label will render in place of the meta key in the Attributes panel — in this example, the label would replace movie_director. The label will also render under certain circumstances in other parts of the editor, including as a placeholder for Rich Text if a block is bound to the post meta source and a default value is undefined.
Usage In Custom Post Templates
One of the primary use cases for Block Bindings is to assist in creating templates for custom post types. Given a custom post typeCustom Post TypeWordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. called movie, for example, one can define how custom fields for that post type will render, such as via connected images, headings, paragraphs, and buttons.
Here is an example of how one could use connected blocks to create a layout:
One can override the content in connected blocks for each instance of the custom post type, a much simpler and more flexible way of creating layouts than in the past — all without needing to create custom blocks.
Default Permissions
Accompanying this UI is a new canUpdateBlockBindings editor setting, used to determine whether the UI is interactive for users or not.
By default, this editor setting is set to a new edit_block_binding capability, which maps to a user’s ability to either:
Edit the post type (in the post editor), or
Edit the theme options (in the site editor)
This means that the setting is by default set to true for administrators, and false for other users.
This default setting can be overridden using the block_editor_settings_allfilterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. and modifying $editor_settings['canUpdateBlockBindings'] as follows:
Several functions have been exposed to enable the use of block bindings in the editor.
Registration API
Source Bootstrapping
As part of the new editor API, Block Bindings will automatically register custom sources defined on the server with bootstrapped values in the editor. This will allow existing sources registered using just the server APIs to render in the UI.
This means that any sources already registered using the server APIs, available since 6.5, will appear in the UI, at least minimally, without any action required.
For example, given the following server registration and block markup…
…the source will get registered in the editor with the source’s name my-plugin/post-attributes, label, and uses_context values. This is enough for the UI to render as follows:
In this case, however, the bound paragraph in the block canvas will simply show the source label and will not be dynamic. Further customization of the editor experience requires using the new editor registration functions, detailed in the next section.
Editor Registration
The following functions have been exposed to allow customization of the editor experience:
registerBlockBindingsSource: Registers a source on the client (using this function will override the bootstrapped registration).
unregisterBlockBindingsSource: Unregisters an existing source.
getBlockBindingsSource: Gets a specific registered source and its properties.
getBlockBindingsSources: Gets all the registered sources in the client.
These are based on other registration APIs like block types, block variations, or block collections.
Source Properties
Registered sources in the client can include the following properties:
name: The unique and machine-readable name.
label: Human-readable label. Will overwrite preexisting label if it has already been registered on the server.
usesContext: Array of context needed by the source only in the editor. Will be merged with existing uses_context if it has already been registered on the server.
getValues: Function to get the values from the source. It receives select, clientId, context, and the block bindings created for that specific source. It must return an object with attribute: value. Similar to getBlockAttributes.
setValues: Function to update multiple values connected to the source. It receives select, clientId, dispatch, context, and the block bindings created for that specific source, including the new value. Similar to updateBlockAttributes.
canUserEditValue: Function to let the editor know if the block attribute connected should be editable or not. It receives select, context, and the source arguments.
Example Usages
Register a Block Bindings Source
Building on the example server registration, use the following JavaScriptJavaScriptJavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. to register in the editor by enqueuing on the enqueue_block_editor_assets hook:
Note: If desired, sources may be registered only on the client and not on the server at all. This could be useful for creating forms in the adminadmin(and super admin), or otherwise using bindings to interact with other parts of WordPress, or other dynamic data.
Block Bindings Utils
The useBlockBindingsUtils hook returns helper functions to modify the metadata.bindings attribute. The hook accepts an optional clientId argument. If the clientId is not specified, the helper functions will execute in the current block edit context.
Right now, the helpers include:
updateBlockBindings: This works similarly to updateBlockAttributes. It can be used to create, update, or remove specific connections.
removeAllBlockBindings: This is used to remove all existing connections in a block.
Example usage
import { useBlockBindingsUtils } from '@wordpress/block-editor';
const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils();
// Updates bindings for url and alt attributes.
updateBlockBindings( {
url: {
source: 'core/post-meta',
args: {
key: 'url_custom_field',
},
},
alt: {
source: 'core/post-meta',
args: {
key: 'alt_custom_field',
},
},
} );
// Removes all bindings set for the block.
removeAllBlockBindings();
Used internally by the default UI for the post meta source and pattern overrides, these utils can be useful in building custom UI for other sources.
A block_bindings_source_value filter has been introduced to allow for overriding of the value returned by a source in a bound block. It takes the following arguments:
value: Value returned by the source.
name: Name of the source.
source_args: Arguments passed to the source.
block_instance: The bound block.
attribute_name: The connected attribute in the bound block.
The developers behind Block Bindings are always happy to hear feedback. Please feel free to share bugs, feature requests, or other thoughts by creating issues on GithubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ or leaving a comment on this post.
Anyone can also follow and comment on Block Bindings development via the latest iteration, which is posted in the Block Bindings tracking issue at the beginning of each release cycle. Be sure to subscribe to the tracking issue for updates!
Lastly, if you’d like to help shape the roadmap for Block Bindings by sharing your use cases, feel free to post in Block Bindings discussions.
WordPress 6.5 introduced the Block Bindings API, which, among other things, allows users to easily connect blocks to custom fields. For example, users can directly connect paragraph content without the need to create a custom blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience., and it will show the selected post metaMetaMeta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. value.
Until now, when this connection existed, the UIUIUser interface to edit the paragraph was locked, preventing users from modifying its value.
WordPress 6.6 introduces the possibility of editing the value of the custom fieldCustom FieldCustom Field, also referred to as post meta, is a feature in WordPress. It allows users to add additional information when writing a post, eg contributors’ names, auth. WordPress stores this information as metadata. Users can display this meta data by using template tags in their WordPress themes. directly from the block when they are connected.
You can see the potential of it in this quick demo:
As can be seen in the video, whenever a block attribute is connected to the Post Meta source, it automatically connects to the custom field value while editing.
Among improvements to the UI to clarify when a block is connected, it comes with some functionalities that are worth mentioning as well:
Custom fields can be updated from a query loopLoopThe Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop.
While using blocks in the query loop, if they are connected to Post Meta, they are also editable.
When multiple blocks are connected to the same custom field, their value is synced
Users can only edit the custom fields from posts where they have permission
Right now, this is restricted to coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. sources like Post Meta or Pattern Overrides, but the idea is to open the relevant APIs to be used by any external source as well.
Read more about this iteration for Block Bindings at #60956
WordPress 6.5 is introducing a new way of extending blocks that substantially reduces the custom code needed to integrate different kinds of data in the blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor.
This can now be done through the new Block Bindings APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways..
What is the Block Bindings API?
Given a coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. block, rather than displaying a user’s inline written content inside of it, imagine wanting to populate that block with data from a particular source instead. For example, the post metadata or custom PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher logic. What would be the process for doing that?
This is actually a trick question: In previous versions of WordPress, you were unable to do this with GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/’s core blocks — it would instead require creating a custom block with particular logic for reading from the source in question. But this is no longer the case.
With the Block Bindings API, you can now bind core blocks to read from different sources without needing to write custom block boilerplate — this means it is possible to bind a Paragraph to read from a post’s metadata, or a Heading to read from a pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party’s PHP logic, all without needing to deal with ReactReactReact is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/., block registration, and other particulars of writing custom blocks from scratch for each new source you want to read from.
This initial release of the Block Bindings API in WordPress 6.5 is a big step towards simplifying the process of extending the editor and expanding the capabilities of blocks. Under the hood, the API already powers a showcase feature being shipped in WordPress 6.5 alongside it: Connecting core blocks to custom fields in the post metadata.
Using the same functionality, as an advanced use case, it is also possible to define and have blocks read from custom sources — more on that briefly below.
Note: For a more detailed walkthrough on creating and using Block Bindings than can be related in this brief dev notedev noteEach important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase., see the Introducing Block Bindings tutorial from the WordPress Developer Blogblog(versus network, site).
How do block bindings work?
Overview
Before getting into the rich functionality Block Bindings can enable via custom sources, this section will first review how the API works in general, then detail how to bind core blocks to custom fields in the post metadata.
The following table shows the current compatible blocks and attributes that can be bound:
Supported Blocks
Supported Attributes
Image
url, alt, title
Paragraph
content
Heading
content
Button
url, text, linkTarget, rel
While the list of compatibility is short for now, this already enables a wide range of use cases, and support for the rest of the core blocks, as well as custom blocks, is planned for the future.
To use Block Bindings, you would specify that these attributes should be read from particular registered sources using the block markup; the logic for those sources would then be executed when rendering on the frontend.
Upon being bound, editing of the attribute in question will be locked and indicators will appear in the editor to signal that the binding has been created.
Specifically, here is how to make use of this via the built-in custom fields support.
Custom fields
Importantly, in this first version of the Block Bindings API, there is no UIUIUser interface for binding attributes to custom fields yet. Therefore, it is necessary to add the markup manually using the Code Editor in Gutenberg.
To bind a supported attribute to a custom fieldCustom FieldCustom Field, also referred to as post meta, is a feature in WordPress. It allows users to add additional information when writing a post, eg contributors’ names, auth. WordPress stores this information as metadata. Users can display this meta data by using template tags in their WordPress themes. in the post metadata, you would use markup such as the following:
In order for this to work, you would need to make sure the field is registered to the post metadata by including code such as the following in the theme’s functions.php or a plugin.
*Note that the show_in_rest property must be set to true for the time being due to security considerations, though there are plans to explore how to remove this requirement in the future.
Future sources
Support for post metadata is just a start, and the plan is to add more built-in sources, such as site, user, and taxonomyTaxonomyA taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. data, for WordPress 6.6.
That being said, the Block Bindings API already has the functionality to allow for registering of custom sources as well, which is the same functionality used internally to register the core/post-meta source above.
Registering a custom source
Overview
To register a Block Bindings source, one needs to use the register_block_bindings_source() function, which has the following signature:
$source_name: A unique name for the custom binding source in the form of namespace/slug. The namespace is required.
$source_properties: An array of properties to define the binding source:
label: An internationalized text string to represent the binding source. Note: this is not currently shown anywhere in the UI.
get_value_callback: A PHP callable (function, closure, etc.) that is called when a block’s bound attribute source matches the $source_name parameter.
uses_context:(Optional) Extends the block instance with an array of contexts if needed for the callback. For example, to use the current post ID, it should be set to [ 'postId' ].
When WordPress encounters the custom bindings source while parsing a block, it will run the get_value_callbackfunction, whose signature should look like this:
Of course, this is a simple example, and you could make use of the other parameters in the callback signature to create more extensive logic.
Additional API functions
Additionally, there are a few other functions currently part of the public API:
unregister_block_bindings_source( $string source_name ): Unregisters a source
get_all_registered_block_bindings_sources(): Gets all registered sources
get_block_bindings_source( $string source_name ): Retrieves a registered source
Also, please note that while the core sources use shared APIs in the editor UI, be aware that these editor APIs will remain private for the time being while discussion continues on how to standardize extensions to the UI around this feature.
This means that if you would like to implement a UI to handle your custom fields easily, for now, you will need to create that functionality yourself.
With that in mind, Block Bindings are just getting started, and future plans include:
Add the possibility of editing the value of the metaMetaMeta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. fields directly from the UI.
Add UI to allow users to add bindings through the Editor.
Create new built-in sources: Site data, post data, and taxonomy data.
Add support for more core blocks.
Add the ability for developers to extend the Editor UI.
As always, feedback is more than welcome, and we invite you to share your ideas and use cases on Github, this post, or WordPress SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. to help shape the development of the Block Bindings API.
A big thanks to @greenshady for providing code snippets and the initial ideas for this post, as well as @santosguillamot, and @czapla for offering their feedback.
You must be logged in to post a comment.