register_block_bindings_source() │ WP 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() 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 -->

Хуков нет.

Возвращает

WP_Block_Bindings_Source|false. Source when the registration was successful, or false on failure.

Использование

register_block_bindings_source( $source_name, $source_properties );

$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.

$source_properties(массив) (обязательный)

The array of arguments that are used to register a source.

• label(строка)
  The label of the source.

• get_value_callback(callable)
  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.
• uses_context(string[])
  Optional. Array of values to add to block uses_context needed by the source.

Список изменений

Код register_block_bindings_source() register block bindings source ^{WP 6.7.2}

function register_block_bindings_source( string $source_name, array $source_properties ) {
	return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
}