- md5
- d76ad0d216678e657d769b12144f9de2
- sha1
- 3fd255705e5338e0640c8f32a807e5c91580deab
- sha256
- 0d64e23f54ea50d240915eb230b0c12ea6098d478f999a62af2c5b340c1435ae
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
<?php
/**
* Block Bindings API
*
* Contains functions for managing block bindings in WordPress.
*
* @package WordPress
* @subpackage Block Bindings
* @since 6.5.0
*/
/**
* Registers a new block bindings source.
*
* Registering a source consists of defining a **name** for that source and a callback function specifying
* how to get a value from that source and pass it 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.
*
* Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook.
*
*
* ## Example
*
* ### Registering a source
*
* First, you need to define a function that will be used to get the value from the source.
*
* function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {
* // Your custom logic to get the value from the source.
* // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API.
* $value = $source_args['key'];
*
* return "The value passed to the block is: $value"
* }
*
* The `$source_args` will contain the arguments passed to the source in the block's
* `metadata.bindings` attribute. See the example in the "Usage in a block" section below.
*
* function my_plugin_register_block_bindings_sources() {
* register_block_bindings_source( 'my-plugin/my-custom-source', array(
* 'label' => __( 'My Custom Source', 'my-plugin' ),
* 'get_value_callback' => 'my_plugin_get_custom_source_value',
* ) );
* }
* add_action( 'init', 'my_plugin_register_block_bindings_sources' );
*
* ### Usage in a block
*
* In a block's `metadata.bindings` attribute, you can specify the source and
* its arguments. Such a block will use the source to override the block
* attribute's value. For example:
*
* <!-- wp:paragraph {
* "metadata": {
* "bindings": {
* "content": {
* "source": "my-plugin/my-custom-source",
* "args": {
* "key": "you can pass any custom arguments here"
* }
* }
* }
* }
* } -->
* <p>Fallback text that gets replaced.</p>
* <!-- /wp:paragraph -->
*
* @since 6.5.0
*
* @param string $source_name The name of the source. It must be a string containing a namespace prefix, i.e.
* `my-plugin/my-custom-source`. It must only contain lowercase alphanumeric
* characters, the forward slash `/` and dashes.
* @param array $source_properties {
* The array of arguments that are used to register a source.
*
* @type string $label The label of the source.
* @type callable $get_value_callback A callback executed when the source is processed during block rendering.
* The callback should have the following signature:
*
* `function( $source_args, $block_instance, $attribute_name ): mixed`
* - @param array $source_args Array containing source arguments
* used to look up the override value,
* i.e. {"key": "foo"}.
* - @param WP_Block $block_instance The block instance.
* - @param string $attribute_name The name of an attribute.
* The callback has a mixed return type; it may return a string to override
* the block's original value, null, false to remove an attribute, etc.
* @type string[] $uses_context Optional. Array of values to add to block `uses_context` needed by the source.
* }
* @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure.
*/
function register_block_bindings_source( string $source_name, array $source_properties ) {
return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
}
/**
* Unregisters a block bindings source.
*
* @since 6.5.0
*
* @param string $source_name Block bindings source name including namespace.
* @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise.
*/
function unregister_block_bindings_source( string $source_name ) {
return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name );
}
/**
* Retrieves the list of all registered block bindings sources.
*
* @since 6.5.0
*
* @return WP_Block_Bindings_Source[] The array of registered block bindings sources.
*/
function get_all_registered_block_bindings_sources() {
return WP_Block_Bindings_Registry::get_instance()->get_all_registered();
}
/**
* Retrieves a registered block bindings source.
*
* @since 6.5.0
*
* @param string $source_name The name of the source.
* @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered.
*/
function get_block_bindings_source( string $source_name ) {
return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name );
}
The same content is in 66 releases, WordPress 6.6-beta3 to 6.8.12. See them all, or every version of this file.