Block bindings: Adds a filter to customize the output of a block bindings source. #6839

snehapatil2001 · 2024-06-17T11:27:12Z

Ticket: https://core.trac.wordpress.org/ticket/61181

Description

This PR introduces a filter to the block_bindings_source_value to allow developers to modify the value returned by any block binding source.
This enhancement provides greater flexibility for developers who need to modify the displayed content of a meta value, such as showing "Free!" when the meta value is 0 or unset.

…_value.

github-actions · 2024-06-17T11:27:32Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props snehapatil02, cbravobernal, gziolo, santosguillamot, bacoords.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2024-06-17T11:39:43Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

SantosGuillamot · 2024-06-26T09:01:31Z

Thanks for working on this! 🙂 I believe something like this could make sense, but I am not sure how it should be structured. Some of the concerns I have at this point:

This filter would only run in the server, which means it would show a different value in the editor. I assume that could be a problem.
Does this only apply to post meta or to any binding?
If it only applies to post meta, should we add the filter to the bindings logic or directly to get_post_meta / get_metadata function? Does this only apply to bindings or each time you want to retrieve the field?

gziolo · 2024-06-26T10:26:18Z

If it only applies to post meta, should we add the filter to the bindings logic or directly to get_post_meta / get_metadata function? Does this only apply to bindings or each time you want to retrieve the field?

There is already an existing filter in get_metadata_raw used internally:

get_{$meta_type}_metadata

SantosGuillamot · 2024-07-01T11:48:04Z

Thinking about this a bit more, I feel more confident that we should probably provide a general filter for bindings that receive the source and the same arguments as get_value_callback. Something similar to the render_block filters. This way, it would be possible to change the value not only of post meta but any other source as well.

…rce but before it's returned.

snehapatil2001 · 2024-07-01T16:38:57Z

@SantosGuillamot Introduced a general filter 'block_bindings_source_value' to allow developers to modify the value returned by any block binding source.

Changes Made:

Modified the get_value method in the WP_Block_Bindings_Source class to apply the new filter.
The filter is applied after the value is retrieved from the source but before it's returned.

Key Benefits:

Flexibility: Works for all binding sources, not just post meta.
Consistency: Functions identically in both the editor and on the front end.
Non-intrusive: It doesn't interfere with existing metadata filters but provides a new layer of customization specific to block bindings.

bacoords · 2024-07-16T13:56:31Z

+1 for this concept. I'll give a real world example and you can tell me if you think this feature would help.

I recently wrote a block variation for the image block to pull in the featured image (yes there's a "featured image" block, but the image block has more options, like the lightbox control). I couldn't use the core/postmeta field where the featured image is stored because it returns an attachment ID, not a URL. So I had to create a custom binding source.

It'd be much less overhead if I could have modified the value sent to the block binding API to return the URL of the featured image instead of the attachment ID. But now I have a custom binding source for one simple meta field AND there's no editor preview on my variation.

Feels like this would be a great example of when this feature would be useful.

SantosGuillamot · 2024-07-18T08:01:19Z

Thanks for making the changes 🙂 I agree it makes sense to have a filter like this.

I must say that I had this on my to-do list for a while, but I didn't find time yet with the 6.6 release. I'm really sorry for the wait. I would like to take a deeper look and understand better all the use cases.

In the meantime, would it make sense to add some testing? Is this something done for other similar filters?

Feels like this would be a great example of when this feature would be useful.

I'd need to review your implementation, but at first glance, it looks like a good example for this functionality 🙂

gziolo

Example of how filters are tested in different places:

wordpress-develop/tests/phpunit/tests/blocks/register.php

Lines 1381 to 1397 in dea027e

    
           	/** 
        
           	 * @ticket 52138 
        
           	 */ 
        
           	public function test_filter_block_registration_metadata_settings() { 
        
           		$filter_metadata_registration = static function ( $settings, $metadata ) { 
        
           			$settings['api_version'] = $metadata['apiVersion'] + 1; 
        
           			return $settings; 
        
           		}; 
        
           		add_filter( 'block_type_metadata_settings', $filter_metadata_registration, 10, 2 ); 
        
           		$result = register_block_type_from_metadata( 
        
           			DIR_TESTDATA . '/blocks/notice' 
        
           		); 
        
           		remove_filter( 'block_type_metadata_settings', $filter_metadata_registration ); 
        
           		$this->assertSame( 3, $result->api_version ); 
        
           	}

This is looking very good and the placement for the filter makes perfect sense. Let's bring it to the finish line.

src/wp-includes/class-wp-block-bindings-source.php

SantosGuillamot · 2024-08-28T14:47:17Z

It seems this is close to being ready. Adding some tests and docs, as suggested below, should be enough to include it in the WordPress 6.7 release.

Thanks a lot for working on it @snehapatil2001! Let us know if you'd like some help in that regard 🙂

gziolo

I left some additional comments clarifying my previous feedback. In addition to that, we still need unit tests to cover the usage as explained in #6839 (review).

gziolo · 2024-09-03T07:41:22Z

src/wp-includes/class-wp-block-bindings-source.php

+		/**
+		 * Filters the output of a block bindings source.
+		 *
+		 * @since 6.7.0
+		 *
+		 * @param mixed $value Value returned by `get_value_callback` after applying the filter.
+		 */
+		$value = call_user_func_array( $this->get_value_callback, array( $source_args, $block_instance, $attribute_name ) );
+		return apply_filters( 'block_bindings_source_value', $value, $this->name, $source_args, $block_instance, $attribute_name );


It still needs some further refinements, so it gets correctly recognized by the parser that generates the documentation for all filters:

Suggested change

/**

* Filters the output of a block bindings source.

*

* @since 6.7.0

*

* @param mixed $value Value returned by `get_value_callback` after applying the filter.

*/

$value = call_user_func_array( $this->get_value_callback, array( $source_args, $block_instance, $attribute_name ) );

return apply_filters( 'block_bindings_source_value', $value, $this->name, $source_args, $block_instance, $attribute_name );

$value = call_user_func_array( $this->get_value_callback, array( $source_args, $block_instance, $attribute_name ) );

/**

* Filters the value of a block bindings source.

*

* @since 6.7.0

*

* @param mixed $value The computed value for the source.

* @param string $name The name of the source.

* @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.

*/

return apply_filters( 'block_bindings_source_value', $value, $this->name, $source_args, $block_instance, $attribute_name );

src/wp-includes/class-wp-block-bindings-source.php

cbravobernal · 2024-09-03T09:16:11Z

I left some additional comments clarifying my previous feedback. In addition to that, we still need unit tests to cover the usage as explained in #6839 (review).

Changes addressed.
Are we sure we want the filter to return a function instead of a value? It's kind of confusing with the name.

function filter_block_bindings_source_value() {
		return function () {
			return 'Filtered value';
		};
	}

src/wp-includes/class-wp-block-bindings-source.php

gziolo · 2024-09-03T09:19:55Z

tests/phpunit/tests/block-bindings/postMetaSource.php

+
+	public function test_filter_block_bindings_source_value() {


Nit: the empty line should get removed.

Suggested change

public function test_filter_block_bindings_source_value() {

public function test_filter_block_bindings_source_value() {

By the way, I think this test should be general purpose in the first place as it isn't tied to post meta, so maybe render.php in the same folder would be a good fit. Having, two tests could work, too.

I'll move it to render.php

tests/phpunit/tests/block-bindings/postMetaSource.php

gziolo · 2024-09-03T09:37:51Z

I left some additional comments clarifying my previous feedback. In addition to that, we still need unit tests to cover the usage as explained in #6839 (review).

Changes addressed. Are we sure we want the filter to return a function instead of a value? It's kind of confusing with the name.
function filter_block_bindings_source_value() {
		return function () {
			return 'Filtered value';
		};
	}

This is what I tested locally and you don't need to pass a function that returns a function:

Index: tests/phpunit/tests/block-bindings/postMetaSource.php
===================================================================
--- tests/phpunit/tests/block-bindings/postMetaSource.php	(revision 58970)
+++ tests/phpunit/tests/block-bindings/postMetaSource.php	(working copy)
@@ -266,4 +266,41 @@
 			'The post content should not include the script tag.'
 		);
 	}
+
+	/**
+	 * Tests that filter `block_bindings_source_value` is applied.
+	 *
+	 * @ticket 61181
+	 */
+	public function test_filter_block_bindings_source_value() {
+		register_meta(
+			'post',
+			'tests_filter_field',
+			array(
+				'show_in_rest' => true,
+				'single'       => true,
+				'type'         => 'string',
+				'default'      => 'Original value',
+			)
+		);
+
+		$filter_value = function ( $value, $source_name, $source_args ) {
+			if ( 'core/post-meta' !== $source_name ) {
+				return $value;
+			}
+			return "Filtered value: {$source_args['key']}";
+		};
+
+		add_filter( 'block_bindings_source_value', $filter_value, 10, 3 );
+
+		$content = $this->get_modified_post_content( '<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"core/post-meta","args":{"key":"tests_filter_field"}}}}} --><p>Fallback value</p><!-- /wp:paragraph -->' );
+
+		remove_filter( 'block_bindings_source_value', $filter_value );
+
+		$this->assertSame(
+			'<p>Filtered value: tests_filter_field</p>',
+			$content,
+			'The post content should show the filtered value.'
+		);
+	}
 }

I also updated the test to validate that the args get correctly passed. Like I said in #6839 (comment), there should be another test in render.php that validates that all args are correctly passed to the filter.

SantosGuillamot · 2024-09-03T12:50:13Z

I've been testing it locally and everything seems to be working as expected. Once the changes to the render.php tests are made, I believe this should be ready.

gziolo · 2024-09-03T13:02:07Z

I've been testing it locally and everything seems to be working as expected. Once the changes to the render.php tests are made, I believe this should be ready.

Agreed, the existing test for post meta is nice to keep as it covers 3 params ($filter_value = function ( $value, $source_name, $source_args ) {), but there is one more param to cover, and it can work with a custom source fine, too.

cbravobernal · 2024-09-03T14:53:52Z

I've been testing it locally and everything seems to be working as expected. Once the changes to the render.php tests are made, I believe this should be ready.

Agreed, the existing test for post meta is nice to keep as it covers 3 params ($filter_value = function ( $value, $source_name, $source_args ) {), but there is one more param to cover, and it can work with a custom source fine, too.

Done!

gziolo

Excellent, this looks solid!

cbravobernal · 2024-09-03T16:34:52Z

Committed in https://core.trac.wordpress.org/changeset/58972

colorful-tones · 2024-10-01T20:51:32Z

@gziolo @cbravobernal

I wonder if this might be a simple and proper example of how to filter a meta value using this new filter?

https://gist.github.com/colorful-tones/b6a2dd85e66dd4adb1d58c0ed1623a61#file-demo-block-bindings-php-L43-L62

gziolo · 2024-10-02T05:28:42Z

@colorful-tones, it’s correct. The reasoning for this new filter is to allow formatting of the value depending on the context. Some examples:

store a price as a number but show with different currencies on the page
store timestamp but show formatted date
add a translated prefix if the value is set

cbravobernal · 2024-10-03T09:43:04Z

Sure, we can use them for future docs and the dev note.

feat: Add filter to customize output of _block_bindings_post_meta_get…

3e636cd

…_value.

SantosGuillamot mentioned this pull request Jul 1, 2024

Block Bindings iteration for WordPress 6.7 WordPress/gutenberg#63018

Open

64 tasks

snehapatil2001 added 3 commits July 1, 2024 21:43

Merge branch 'trunk' into feature/add-post-meta-value-filter

fb9c797

feat: the filter is applied after the value is retrieved from the sou…

f882729

…rce but before it's returned.

fix: phpcs errors.

ae25e24

Merge branch 'trunk' into feature/add-post-meta-value-filter

b5cfd83

gziolo reviewed Jul 18, 2024

View reviewed changes

src/wp-includes/class-wp-block-bindings-source.php Show resolved Hide resolved

src/wp-includes/class-wp-block-bindings-source.php Show resolved Hide resolved

SantosGuillamot mentioned this pull request Aug 9, 2024

Block Bindings: Improve how bindings handle placeholder/fallback values WordPress/gutenberg#63442

Closed

cbravobernal added 2 commits September 2, 2024 18:18

Restore since

c4d9b86

Add filter docs

c360541

gziolo reviewed Sep 3, 2024

View reviewed changes

cbravobernal added 3 commits September 3, 2024 10:58

Add unit test for filter

7edc027

Adapt docs

95798f4

Apply format

e7e56af

gziolo reviewed Sep 3, 2024

View reviewed changes

src/wp-includes/class-wp-block-bindings-source.php Outdated Show resolved Hide resolved

gziolo reviewed Sep 3, 2024

View reviewed changes

tests/phpunit/tests/block-bindings/postMetaSource.php Outdated Show resolved Hide resolved

cbravobernal added 3 commits September 3, 2024 11:24

Edit description

093245d

Remove extra spaces

05d2dc1

More format

4979c9d

Refactor test to include all args

0a8b762

cbravobernal added 5 commits September 3, 2024 16:20

Add test on render

6edcc15

Remove not needed args

c112469

Update test message

f1223ee

Some spacing

1e5d633

Add 5 vars

5af69a6

Save some bytes by returning empty string

e52dbc2

gziolo approved these changes Sep 3, 2024

View reviewed changes

cbravobernal changed the title ~~Implement a filter to customize output on _block_bindings_post_meta_get_value.~~ Block bindings: Add a filter to customize the output of a block bindings source. Sep 3, 2024

cbravobernal changed the title ~~Block bindings: Add a filter to customize the output of a block bindings source.~~ Block bindings: Adds a filter to customize the output of a block bindings source. Sep 3, 2024

cbravobernal closed this Sep 3, 2024

zaguiini mentioned this pull request Sep 5, 2024

Block Bindings: Remove getPlaceholder API and rely on key argument or source label WordPress/gutenberg#64910

Merged

SantosGuillamot mentioned this pull request Oct 8, 2024

Use block bindings instead of custom blocks for some actors / movies data. WordPress/wp-movies-demo#72

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Block bindings: Adds a filter to customize the output of a block bindings source. #6839

Block bindings: Adds a filter to customize the output of a block bindings source. #6839

snehapatil2001 commented Jun 17, 2024 •

edited by cbravobernal

Loading

github-actions bot commented Jun 17, 2024 •

edited

Loading

github-actions bot commented Jun 17, 2024

SantosGuillamot commented Jun 26, 2024

gziolo commented Jun 26, 2024

SantosGuillamot commented Jul 1, 2024

snehapatil2001 commented Jul 1, 2024

bacoords commented Jul 16, 2024

SantosGuillamot commented Jul 18, 2024

gziolo left a comment

SantosGuillamot commented Aug 28, 2024

gziolo left a comment

gziolo Sep 3, 2024

cbravobernal commented Sep 3, 2024

gziolo Sep 3, 2024

gziolo Sep 3, 2024

cbravobernal Sep 3, 2024

gziolo commented Sep 3, 2024 •

edited

Loading

SantosGuillamot commented Sep 3, 2024

gziolo commented Sep 3, 2024

cbravobernal commented Sep 3, 2024

gziolo left a comment

cbravobernal commented Sep 3, 2024

colorful-tones commented Oct 1, 2024

gziolo commented Oct 2, 2024

cbravobernal commented Oct 3, 2024

	/**
	* @ticket 52138
	*/
	public function test_filter_block_registration_metadata_settings() {
	$filter_metadata_registration = static function ( $settings, $metadata ) {
	$settings['api_version'] = $metadata['apiVersion'] + 1;
	return $settings;
	};

	add_filter( 'block_type_metadata_settings', $filter_metadata_registration, 10, 2 );
	$result = register_block_type_from_metadata(
	DIR_TESTDATA . '/blocks/notice'
	);
	remove_filter( 'block_type_metadata_settings', $filter_metadata_registration );

	$this->assertSame( 3, $result->api_version );
	}


	public function test_filter_block_bindings_source_value() {
	public function test_filter_block_bindings_source_value() {

Block bindings: Adds a filter to customize the output of a block bindings source. #6839

Block bindings: Adds a filter to customize the output of a block bindings source. #6839

Conversation

snehapatil2001 commented Jun 17, 2024 • edited by cbravobernal Loading

Ticket: https://core.trac.wordpress.org/ticket/61181

Description

github-actions bot commented Jun 17, 2024 • edited Loading

github-actions bot commented Jun 17, 2024

Test using WordPress Playground

Some things to be aware of

SantosGuillamot commented Jun 26, 2024

gziolo commented Jun 26, 2024

SantosGuillamot commented Jul 1, 2024

snehapatil2001 commented Jul 1, 2024

bacoords commented Jul 16, 2024

SantosGuillamot commented Jul 18, 2024

gziolo left a comment

Choose a reason for hiding this comment

SantosGuillamot commented Aug 28, 2024

gziolo left a comment

Choose a reason for hiding this comment

gziolo Sep 3, 2024

Choose a reason for hiding this comment

cbravobernal commented Sep 3, 2024

gziolo Sep 3, 2024

Choose a reason for hiding this comment

gziolo Sep 3, 2024

Choose a reason for hiding this comment

cbravobernal Sep 3, 2024

Choose a reason for hiding this comment

gziolo commented Sep 3, 2024 • edited Loading

SantosGuillamot commented Sep 3, 2024

gziolo commented Sep 3, 2024

cbravobernal commented Sep 3, 2024

gziolo left a comment

Choose a reason for hiding this comment

cbravobernal commented Sep 3, 2024

colorful-tones commented Oct 1, 2024

gziolo commented Oct 2, 2024

cbravobernal commented Oct 3, 2024

snehapatil2001 commented Jun 17, 2024 •

edited by cbravobernal

Loading

github-actions bot commented Jun 17, 2024 •

edited

Loading

gziolo commented Sep 3, 2024 •

edited

Loading