From 95997e6ec2b0550b6b86604a97e21f1e006183e5 Mon Sep 17 00:00:00 2001 From: Michal Czaplinski Date: Mon, 5 Feb 2024 14:29:46 +0000 Subject: [PATCH 1/7] Do not escape the attribute passed to `$processor->set_attribute()` --- src/wp-includes/class-wp-block.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/wp-includes/class-wp-block.php b/src/wp-includes/class-wp-block.php index 80757baabce39..9f58a5fe45d8e 100644 --- a/src/wp-includes/class-wp-block.php +++ b/src/wp-includes/class-wp-block.php @@ -376,7 +376,7 @@ private function replace_html( string $block_content, string $attribute_name, $s ) ) { return $block_content; } - $amended_content->set_attribute( $block_type->attributes[ $attribute_name ]['attribute'], esc_attr( $source_value ) ); + $amended_content->set_attribute( $block_type->attributes[ $attribute_name ]['attribute'], $source_value ); return $amended_content->get_updated_html(); break; From 75d4cf39e9ec9649023284c052ff16739ab3eb7a Mon Sep 17 00:00:00 2001 From: Michal Czaplinski Date: Mon, 5 Feb 2024 16:37:00 +0000 Subject: [PATCH 2/7] Ad block bindings registration PHP docstrings with example usage --- src/wp-includes/block-bindings.php | 44 +++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/src/wp-includes/block-bindings.php b/src/wp-includes/block-bindings.php index 4fc58c3325ba8..d040ad8f5b018 100644 --- a/src/wp-includes/block-bindings.php +++ b/src/wp-includes/block-bindings.php @@ -12,10 +12,46 @@ /** * Registers a new block bindings source. * - * Sources are used to override block's original attributes with a value - * coming from the source. Once a source is registered, it can be used by a - * block by setting its `metadata.bindings` attribute to a value that refers - * to the source. + * Registering a source consists of defining a **name** for that source as well as a callback function + * which specifies 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 + * + * 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' ); + * + * 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. + * } + * + * ### 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: + * + * * * @since 6.5.0 * From ec7325b911391f023475f350f5a2faf9daa46155 Mon Sep 17 00:00:00 2001 From: Michal Czaplinski Date: Tue, 6 Feb 2024 11:56:58 +0000 Subject: [PATCH 3/7] Update the docstring with more exhaustive info --- src/wp-includes/block-bindings.php | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/src/wp-includes/block-bindings.php b/src/wp-includes/block-bindings.php index d040ad8f5b018..16f4d32317c8d 100644 --- a/src/wp-includes/block-bindings.php +++ b/src/wp-includes/block-bindings.php @@ -20,8 +20,22 @@ * * 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. + * return 'my custom 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' ), @@ -30,10 +44,6 @@ * } * add_action( 'init', 'my_plugin_register_block_bindings_sources' ); * - * 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. - * } - * * ### Usage in a block * * In a block's `metadata.bindings` attribute, you can specify the source and From 09d325f28f133daf104391dfe46e8f7e03e752a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Wed, 7 Feb 2024 09:37:52 +0100 Subject: [PATCH 4/7] Update src/wp-includes/block-bindings.php MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damián Suárez --- src/wp-includes/block-bindings.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/wp-includes/block-bindings.php b/src/wp-includes/block-bindings.php index 16f4d32317c8d..6731695c94f5d 100644 --- a/src/wp-includes/block-bindings.php +++ b/src/wp-includes/block-bindings.php @@ -12,8 +12,8 @@ /** * Registers a new block bindings source. * - * Registering a source consists of defining a **name** for that source as well as a callback function - * which specifies how to get a value from that source and pass it to a block attribute. + * 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. From 71b9917beb88cb49d25f9a9913bb36e627facce6 Mon Sep 17 00:00:00 2001 From: Michal Date: Wed, 7 Feb 2024 18:28:24 +0000 Subject: [PATCH 5/7] Add inner content to the example docstring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- src/wp-includes/block-bindings.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/wp-includes/block-bindings.php b/src/wp-includes/block-bindings.php index 6731695c94f5d..9c1f93174da08 100644 --- a/src/wp-includes/block-bindings.php +++ b/src/wp-includes/block-bindings.php @@ -61,7 +61,9 @@ * } * } * } - * } --> + * } --> + *

Fallback text that gets replaced.

+ * * * @since 6.5.0 * From 014af3572b1908e4b0a1a43ec90c85b0aa5e6d13 Mon Sep 17 00:00:00 2001 From: Michal Czaplinski Date: Wed, 7 Feb 2024 18:39:34 +0000 Subject: [PATCH 6/7] Update custom source value logic in block-bindings.php --- src/wp-includes/block-bindings.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/wp-includes/block-bindings.php b/src/wp-includes/block-bindings.php index 9c1f93174da08..7094313959688 100644 --- a/src/wp-includes/block-bindings.php +++ b/src/wp-includes/block-bindings.php @@ -30,7 +30,9 @@ * 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. - * return 'my custom value'; + * $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 From 94385a524085363cdd07b9870109123e2601a63c Mon Sep 17 00:00:00 2001 From: Michal Czaplinski Date: Wed, 7 Feb 2024 18:43:48 +0000 Subject: [PATCH 7/7] Add a note to `WP_Block_Bindings_Registry::register()` pointing to `register_block_bindings_source()` --- src/wp-includes/class-wp-block-bindings-registry.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/wp-includes/class-wp-block-bindings-registry.php b/src/wp-includes/class-wp-block-bindings-registry.php index 28e8b1b60186e..edde1a0cb884e 100644 --- a/src/wp-includes/class-wp-block-bindings-registry.php +++ b/src/wp-includes/class-wp-block-bindings-registry.php @@ -35,6 +35,11 @@ final class WP_Block_Bindings_Registry { /** * Registers a new block bindings source. * + * This is a low-level method. For most use cases, it is recommended to use + * the `register_block_bindings_source()` function instead. + * + * @see register_block_bindings_source() + * * Sources are used to override block's original attributes with a value * coming from the source. Once a source is registered, it can be used by a * block by setting its `metadata.bindings` attribute to a value that refers