Block Bindings: Improvements to the Editor Experience in 6.7

WordPress 6.7 introduces various improvements to the BlockBlock Block 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 APIAPI An 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 metaMeta Meta 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 UIUI User 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:

  1. 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.
  2. 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 Field Custom 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 Type WordPress 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:

  1. Edit the post type (in the post editor), or
  2. 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_all filterFilter Filters 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:

function my_plugin_override_can_update_block_bindings( $settings ) {
    $settings['canUpdateBlockBindings'] = true;
    return $settings;
}
add_action( 'block_editor_settings_all', 'my_plugin_override_can_update_block_bindings' );

New Public Editor APIs

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…

Server Registration
function my_plugin_register_block_bindings_post_attributes() {
    register_block_bindings_source(
        'my-plugin/post-attributes',
        array(
            'label'              => _x( 'Post Attributes', 'block bindings source', 'my-plugin' ),
            'get_value_callback' => 'my_plugin_block_bindings_post_attributes_get_value',
            'uses_context'       => array( 'postId' ),
        )
    );
}
add_action( 'init', 'my_plugin_register_block_bindings_post_attributes' );

function my_plugin_block_bindings_post_attributes_get_value( array $source_args, $block_instance ) {
    $allowed_fields = array( 'title', 'excerpt' );
    if ( ! in_array( $source_args['key'], $allowed_fields ) ) {
        return null;
    }
    $post = get_post( $block_instance->context['postId'] );
    return $post->{'post_' . $source_args['key']};
}
Block Markup
<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"my-plugin/post-attributes","args":{"key":"title"}}}}} -->
<p></p>
<!-- /wp:paragraph -->

…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 JavaScriptJavaScript JavaScript 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:

import { registerBlockBindingsSource } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import { store as coreEditorStore } from '@wordpress/editor';

const allowedAttributes = [ 'title', 'excerpt' ];

registerBlockBindingsSource( {
    name: 'my-plugin/post-attributes',
    usesContext: [ 'postType' ],	
    getValues( { select, bindings } ) {
        const values = {};
        for ( const [ attributeName, source ] of Object.entries( bindings ) ) {
            if ( allowedAttributes.includes( source.args.key ) ) {
                values[ attributeName ] = select( coreEditorStore ).getEditedPostAttribute( source.args.key );
            }
        }
        return values;
    },
    setValues( { dispatch, bindings } ) {
        const newValues = {};
        for ( const [ attributeName, source ] of Object.entries( bindings ) ) {
            if ( allowedAttributes.includes( source.args.key ) ) {
                newValues[ source.args.key ] = source.newValue;
            }
        }
        if ( Object.keys( newValues ).length > 0 ) {
            dispatch( coreEditorStore ).editPost( newValues );
        }
    },
    canUserEditValue( { context, args } ) {
        return allowedAttributes.includes( args.key ) && 'post' === context.postType;
    },
} );

To connect example blocks to the source, go to the post editor, open the code editor, and use the following markup:

<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"my-plugin/post-attributes","args":{"key":"title"}}}}} -->
<p></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"my-plugin/post-attributes","args":{"key":"excerpt"}}}}} -->
<p></p>
<!-- /wp:paragraph -->

For a more in-depth example of how these properties can be defined in a real-world scenario, see the registration for the built-in post meta source.

Unregister a Block Bindings Source
import { unregisterBlockBindingsSource } from '@wordpress/blocks';

unregisterBlockBindingsSource( 'plugin/my-custom-source' );
Get All Block Bindings Sources
import { getBlockBindingsSources } from '@wordpress/blocks';

const registeredSources = getBlockBindingsSources();
Get a Block Bindings Source
import { getBlockBindingsSource } from '@wordpress/blocks';

const blockBindingsSource = getBlockBindingsSource( 'plugin/my-custom-source' );

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.

For more examples of how these functions are used in practice by the built-in UI, see the calls to updateBlockBindings and removeAllBlockBindings.

New Server Filter

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.
function modify_block_bindings_source_value( $value, $name, $source_args, $block_instance, $attribute_name ) {
    if ( 'core/post-meta' === $name && 'movie_runtime' === $source_args['key'] ) {
        return $value . ' minutes';
    }
    return $value;
}
add_filter( 'block_bindings_source_value', 'modify_block_bindings_source_value', 10, 5 );

Conclusion

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 GithubGitHub GitHub 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.

Props to @santosguillamot @gziolo @cbravobernal @greenshady @fabiankaegy and @welcher for their help compiling this post.

#6-7, #block-bindings, #dev-notes, #dev-notes-6-7

Editing custom fields from connected blocks

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 blockBlock Block 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 metaMeta Meta 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 UIUI User 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 Field Custom 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 loopLoop The 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 coreCore Core 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

Props to @juanmaguitar for review

#6-6, #block-bindings

New Feature: The Block Bindings API

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 blockBlock Block 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 APIAPI An 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 coreCore Core 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 PHPPHP The 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?

Screenshot showing a heading and paragraph in the Gutenberg editor, with a large red arrow pointing to the paragraph. The paragraph reads: "How would you replace this sentence with data from somewhere else?"

This is actually a trick question: In previous versions of WordPress, you were unable to do this with GutenbergGutenberg The 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 pluginPlugin A 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 ReactReact React 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 note Each 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 BlocksSupported Attributes
Imageurl, alt, title
Paragraphcontent
Headingcontent
Buttonurl, 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.

Screenshot of the Gutenberg editor; a paragraph is selected and there are icons in the block toolbar, as well as a purple outline around the paragraph, declaring the block as bound.

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 UIUI User 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 Field Custom 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:

<!-- wp:paragraph {
"metadata":{
"bindings":{
"content":{
"source":"core/post-meta",
"args":{
"key":"book-genre"
}
}
}
}
} -->
<p></p>
<!-- /wp:paragraph -->

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.

register_meta(
'post',
'book-genre',
array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default text field',
)
);

*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 taxonomyTaxonomy A 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:

register_block_bindings_source(
string $source_name,
array $source_properties
);

There are two available parameters:

  • $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_callback function, whose signature should look like this:

projectslug_bindings_callback(
array $source_args,
WP_Block $block_instance,
string $attribute_name
);

It can accept up to three parameters, though you don’t need to include them unless your logic requires them:

  • $source_args: An array of arguments passed via the metadata.bindings.$attribute.args property from the block.
  • $block_instance: The current instance of the block the binding is connected to as a WP_Block object.
  • $attribute_name: The current attribute set via the metadata.bindings.$attribute property key on the block.

Using the Registration Mechanism

In practice, here is how you might use the above registration function to create a simple binding 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 '&copy; ' . date( 'Y' );
}

And here is how you would bind a paragraph to the copyright source in the block markup, and how it would look on the frontend:

<!-- wp:paragraph {
"metadata":{
"bindings":{
"content":{
"source":"projectslug/copyright"
}
}
}
} -->
<p>Copyright Block</p>
<!-- /wp:paragraph -->
A screenshot of a post titled "Block Bindings Copyright Example"; in the content is a copyright symbol and the year 2024.

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.

Further learning and next steps

For more inspiration on how to use Block Bindings in your own projects, see the registration logic in block-bindings.php and the built-in core/post-meta source, and take a look at the Introducing Block Bindings tutorial series.

With that in mind, Block Bindings are just getting started, and future plans include:

  • Add the possibility of editing the value of the metaMeta Meta 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 SlackSlack Slack 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.

#6-5, #block-bindings, #dev-notes, #dev-notes-6-5