WordPress 6.5 introduces a new feature: the Block Bindings API. This is a tool that makes the block editor easier to use, and makes it simpler for you to add all kinds of data to different parts of your website. This means you'll have a lot less custom code to write when editing.
What is the Block Binding API?
Suppose you have a basic block that you need to use on a web page to display some information from a specific source, such as the details of an article or some custom rules formulated in PHP code. How do you do it? Here is the way to make it simple and clear.
In previous versions of WordPress, if you wanted to display some special information on a web page, such as extra details for a post or some content customized by PHP logic, you usually needed to create a brand new custom block. This process could be both complicated and time-consuming.
However, starting with WordPress 6.5, things have gotten a lot easier. With the Block Binding API, you can now have an existing standard block, such as a paragraph or title, fetch data directly from a different source without having to make an entirely new block yourself. This means that you can have a paragraph block display metadata for a post directly, or a title block display PHP logic generated by a plugin, all without having to dive into React programming, block registration, or creating a new custom block from scratch.
WordPress 6.5's Block Binding API is a major update that makes extending the editor and blocks much easier. In fact, this new API has been used to demonstrate how to link a post's custom fields to a core block.
Going a little more advanced, you can also use this feature to customize blocks and get data from special sources you set up.
For an in-depth look at how to create and use block bindings, check out the WordPress developer blog on theIntroductory TutorialThe
How does block binding work?
summarize
Before we dive into how to use the Block Binding API to link to a custom data source, we'll briefly explain how this API works. Then, we'll go into more detail about how to link a standard block to a custom field in an article.
Below is a table showing the blocks that can now be linked and their properties:
While there aren't many blocks and attributes that can be used with this new feature right now, they are enough to cover many common needs. In the future, the plan is to extend this feature to more core blocks and custom blocks.
To use block binding, you'll need to set it up to tell WordPress to use specific tags to fetch information from the data sources you choose. Once set up, the logic from those data sources will be used to display the content when it is displayed on the front end of the page.
Once a property is bound, you can't change it in the editor, and the editor displays a flag telling you that the property is already connected to some data source.
Here's an example of how to utilize it with built-in custom field support.
Custom Fields
In the first version of the Block Binding API, there wasn't a direct interface to link properties to custom fields. This means you need to manually go into Gutenberg's code editor to add specific code.
If you want to connect the supported attributes to the custom fields of the article, you can add the code in the following format:
<!-- wp:paragraph {
"metadata":{
"bindings":{
"content":{
"source":"core/post-meta",
"args":{
"key":"book-genre"
}
}
}
}
} -->
<p></p>
<!-- /wp:paragraph -->In order for this to work, you need to add some code to your theme's functions.php file or a plugin so that you can make sure that your custom fields have been successfully registered in the post metadata.
register_meta(
'post',
'book-genre'.
array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default text field',
)
);Keep in mind that, to be safe, you need to temporarily remove theshow_in_restproperty is set totrueThe
More data sources for the future
Supporting post metadata is just the first step. We plan to add more data sources in WordPress 6.6, such as site information, user information, and classifieds.
And, the Block Binding API lets you register your own data sources right now, which is the same functionality we use to register article metadata.
Register a custom source
summarize
To create a new block-bound datasource, you'll need to use a block-bound datasource namedregister_block_bindings_source()function, here is its basic format:
register_block_bindings_source(
string $source_name,
array $source_properties
).To register a new block binding source, you can use two parameters:
- $source_name: This is the unique identifier of your custom data source, and should be in the format "namespace/name". Remember that every data source needs a unique namespace.
- $source_properties: This is an array that defines the characteristics of the data source, including:
- label: This is a text string that describes your data source, although currently this label is not visible in the interface.
- get_value_callback: This is a PHP function or closure that will be called when the block's binding source needs to use the data.
- use_context(optional): this is an array that specifies what should be included if your data source requires additional information (such as the ID of the current article).
When WordPress processes the block and finds a custom data source to load, it calls theget_value_callbackfunction. This function should be set up like this:
projectslug_bindings_callback(
array $source_args,
WP_Block $block_instance,
string $attribute_name
).Use of registration mechanisms
In practice, you can use the following registration functions to create simple bindings for copyright information:
add_action( 'init', 'projectslug_register_block_bindings' );
function projectslug_register_block_bindings() {
register_block_bindings_source( 'projectslug/copyright', array(
'label' => __( 'Copyright', 'projectslug' ),
'get_value_callback' => 'projectslug_copyright_binding'
) );
}
function projectslug_copyright_binding() {
return '© ' . date( 'Y' ); } function projectslug_copyright_binding() { return '© ' .
}Here's an example of how to link a paragraph block to a data source for copyright information, and shows what it looks like on the front end of a website:
<!-- wp:paragraph {
"metadata":{
"bindings":{
"content":{
"source":"projectslug/copyright"
}
}
}
} -->
<p>Copyright Block</p>
<!-- /wp:paragraph -->
Of course, this is just a basic example. You can use other parameters in the function to build more complex functionality.
Other API Functions
In addition, there are a number of other functions that are currently publicly available:
- unregister_block_bindings_source($source_name): Used to deregister an already set data source.
- get_all_registered_block_bindings_sources(): Used to get a list of all registered data sources.
- get_block_bindings_source($source_name): Used to get the details of a specific registered data source.
Note also that while the core data sources are available in the editor's user interface, these APIs for the editor are currently private. This means that we are still discussing how to standardize the use of these features in the user interface.
So if you want an easy-to-use interface for handling custom fields, you now need to develop this feature yourself.
Further study and next steps
Want to get more inspired by using block bindings in your projects? Take a look at theblock-bindings.phpThe registration code in the file and the built-incore/post-metadata sources, and don't miss our block bindings!Introductory Tutorial SeriesThe
block binding is still in its infancy.In the future we plan toRealize the following functions:
- Allows editing of meta field values directly in the user interface.
- Add functionality to the editor to enable users to easily add bindings.
- Introduced new built-in data sources, including site data, article data, and categorized data.
- Extended support for more core blocks.
- Provides tools for developers to extend the editor's user interface.
We very much welcome feedback! You can find out more about us through theGithubor WordPress Slack to share your ideas and use cases with us to help us refine the block binding API together.
