Improve block registration shape to allow query options

Automattic · Dec 27, 2024 · 8aeb229 · 8aeb229
1 parent 8b71833
commit 8aeb229
Show file tree

Hide file tree

Showing 17 changed files with 197 additions and 134 deletions.
diff --git a/docs/extending/block-patterns.md b/docs/extending/block-patterns.md
@@ -20,7 +20,7 @@ Example:
 ```php
 register_remote_data_block( [
 	'title' => 'My Remote Data Block',
-	'queries' => [ /* ... */ ],
+	'render_query' => [ /* ... */ ],
 	'patterns' => [
 		[
 			'title' => 'My Pattern',

diff --git a/docs/extending/block-registration.md b/docs/extending/block-registration.md
@@ -17,7 +17,7 @@ function register_your_custom_block() {
 		],
 	] );
 
-	$display_query = HttpQuery::from_array( [
+	$render_query = HttpQuery::from_array( [
 		'display_name' => 'Example Query',
 		'data_source' => $data_source,
 		'output_schema' => [
@@ -38,8 +38,8 @@ function register_your_custom_block() {
 
 	register_remote_data_block( [
 		'title' => 'My Block',
-		'queries' => [
-			'display' => $display_query,
+		'render_query' => [
+			'query' => $render_query,
 		],
 	] );
 }

diff --git a/docs/workflows/rest-api-with-code.md b/docs/workflows/rest-api-with-code.md
@@ -58,8 +58,8 @@ function register_zipcode_block(): void {
 
 	register_remote_data_block( [
 		'title' => 'Zip Code',
-		'queries' => [
-			'display' => $zipcode_query,
+		'render_query' => [
+			'query' => $zipcode_query,
 		],
 	] );
 }

diff --git a/docs/workflows/rest-api.md b/docs/workflows/rest-api.md
@@ -72,8 +72,8 @@ function register_zipcode_block(): void {
 
 	register_remote_data_block( [
 		'title' => 'Zip Code',
-		'queries' => [
-			'display' => $zipcode_query,
+		'render_query' => [
+			'query' => $zipcode_query,
 		],
 	] );
 }

diff --git a/example/airtable/elden-ring-map/register.php b/example/airtable/elden-ring-map/register.php
@@ -99,9 +99,14 @@ function register_airtable_elden_ring_map_block(): void {
 
 	register_remote_data_block( [
 		'title' => $block_name,
-		'queries' => [
-			'display' => $list_locations_query,
-			'list' => $list_maps_query,
+		'render_query' => [
+			'query' => $list_locations_query,
+		],
+		'selection_queries' => [
+			[
+				'query' => $list_maps_query,
+				'type' => 'list',
+			],
 		],
 		'patterns' => [
 			[

diff --git a/example/github/remote-data-blocks/register.php b/example/github/remote-data-blocks/register.php
@@ -96,17 +96,21 @@ function register_github_file_as_html_block(): void {
 
 	register_remote_data_block( [
 		'title' => $block_title,
-		'queries' => [
-			'display' => $github_get_file_as_html_query,
-			'list' => $github_get_list_files_query,
+		'render_query' => [
+			'query' => $github_get_file_as_html_query,
+			'input_overrides' => [
+				[
+					'source' => 'file_path',
+					'source_type' => 'page',
+					'target' => 'file_path',
+					'target_type' => 'input_var',
+				],
+			],
 		],
-		'query_input_overrides' => [
+		'selection_queries' => [
 			[
-				'query' => 'display',
-				'source' => 'file_path',
-				'source_type' => 'page',
-				'target' => 'file_path',
-				'target_type' => 'input_var',
+				'query' => $github_get_list_files_query,
+				'type' => 'list',
 			],
 		],
 		'pages' => [

diff --git a/example/google-sheets/westeros-houses/register.php b/example/google-sheets/westeros-houses/register.php
@@ -158,17 +158,21 @@ function ( $row, $index ) use ( $columns ) {
 
 	register_remote_data_block( [
 		'title' => 'Westeros House',
-		'queries' => [
-			'display' => $get_westeros_houses_query,
-			'list' => $list_westeros_houses_query,
+		'render_query' => [
+			'query' => $get_westeros_houses_query,
+			'input_overrides' => [
+				[
+					'source' => 'house',
+					'source_type' => 'page',
+					'target' => 'row_id',
+					'target_type' => 'input_var',
+				],
+			],
 		],
-		'query_input_overrides' => [
+		'selection_queries' => [
 			[
-				'query' => 'display',
-				'source' => 'house',
-				'source_type' => 'page',
-				'target' => 'row_id',
-				'target_type' => 'input_var',
+				'query' => $list_westeros_houses_query,
+				'type' => 'list',
 			],
 		],
 		'pages' => [
@@ -181,9 +185,9 @@ function ( $row, $index ) use ( $columns ) {
 
 	register_remote_data_block( [
 		'title' => 'Westeros Houses List',
-		'loop' => true,
-		'queries' => [
-			'display' => $list_westeros_houses_query,
+		'render_query' => [
+			'loop' => true,
+			'query' => $list_westeros_houses_query,
 		],
 	] );
 }

diff --git a/example/rest-api/art-institute/register.php b/example/rest-api/art-institute/register.php
@@ -88,9 +88,14 @@ function register_aic_block(): void {
 
 	register_remote_data_block( [
 		'title' => 'Art Institute of Chicago',
-		'queries' => [
-			'display' => $get_art_query,
-			'search' => $search_art_query,
+		'render_query' => [
+			'query' => $get_art_query,
+		],
+		'selection_queries' => [
+			[
+				'query' => $search_art_query,
+				'type' => 'search',
+			],
 		],
 	] );
 }

diff --git a/example/rest-api/zip-code/register.php b/example/rest-api/zip-code/register.php
@@ -51,8 +51,8 @@ function register_zipcode_block(): void {
 
 	register_remote_data_block( [
 		'title' => 'Zip Code',
-		'queries' => [
-			'display' => $zipcode_query,
+		'render_query' => [
+			'query' => $zipcode_query,
 		],
 	] );
 }

diff --git a/inc/Editor/BlockManagement/ConfigRegistry.php b/inc/Editor/BlockManagement/ConfigRegistry.php
@@ -20,6 +20,8 @@
 class ConfigRegistry {
 	private static LoggerInterface $logger;
 
+	public const RENDER_QUERY_KEY = 'render_query';
+	public const SELECTION_QUERIES_KEY = 'selection_queries';
 	public const DISPLAY_QUERY_KEY = 'display';
 	public const LIST_QUERY_KEY = 'list';
 	public const SEARCH_QUERY_KEY = 'search';
@@ -46,7 +48,7 @@ public static function register_block( array $user_config = [] ): bool|WP_Error
 			return self::create_error( $block_title, sprintf( 'Block %s has already been registered', $block_name ) );
 		}
 
-		$display_query = $user_config['queries'][ self::DISPLAY_QUERY_KEY ];
+		$display_query = $user_config[ self::RENDER_QUERY_KEY ]['query'];
 		$input_schema = $display_query->get_input_schema();
 
 		// Build the base configuration for the block. This is our own internal
@@ -55,7 +57,7 @@ public static function register_block( array $user_config = [] ): bool|WP_Error
 		$config = [
 			'description' => '',
 			'name' => $block_name,
-			'loop' => $user_config['loop'] ?? false,
+			'loop' => $user_config[ self::RENDER_QUERY_KEY ]['loop'] ?? false,
 			'patterns' => [],
 			'queries' => [
 				self::DISPLAY_QUERY_KEY => $display_query,
@@ -82,53 +84,48 @@ public static function register_block( array $user_config = [] ): bool|WP_Error
 
 		// Register "selectors" which allow the user to use a query to assist in
 		// selecting data for display by the block.
-		foreach ( [ self::LIST_QUERY_KEY, self::SEARCH_QUERY_KEY ] as $from_query_type ) {
-			if ( isset( $user_config['queries'][ $from_query_type ] ) ) {
-				$to_query = $display_query;
-				$from_query = $user_config['queries'][ $from_query_type ];
+		foreach ( $user_config[ self::SELECTION_QUERIES_KEY ] ?? [] as $selection_query ) {
+			$from_query = $selection_query['query'];
+			$from_query_type = $selection_query['type'];
+			$to_query = $display_query;
 
-				$config['queries'][ $from_query_type ] = $from_query;
+			$config['queries'][ $from_query::class ] = $from_query;
 
-				$from_input_schema = $from_query->get_input_schema();
-				$from_output_schema = $from_query->get_output_schema();
+			$from_input_schema = $from_query->get_input_schema();
+			$from_output_schema = $from_query->get_output_schema();
 
-				foreach ( array_keys( $to_query->get_input_schema() ) as $to ) {
-					if ( ! isset( $from_output_schema['type'][ $to ] ) ) {
-						return self::create_error( $block_title, sprintf( 'Cannot map key "%s" from %s query', esc_html( $to ), $from_query_type ) );
-					}
-				}
-
-				if ( self::SEARCH_QUERY_KEY === $from_query_type && ! isset( $from_input_schema['search_terms'] ) ) {
-					return self::create_error( $block_title, 'A search query must have a "search_terms" input variable' );
+			foreach ( array_keys( $to_query->get_input_schema() ) as $to ) {
+				if ( ! isset( $from_output_schema['type'][ $to ] ) ) {
+					return self::create_error( $block_title, sprintf( 'Cannot map key "%s" from %s query', esc_html( $to ), $from_query_type ) );
 				}
+			}
 
-				// Add the selector to the configuration.
-				array_unshift(
-					$config['selectors'],
-					[
-						'image_url' => $from_query->get_image_url(),
-						'inputs' => [],
-						'name' => ucfirst( $from_query_type ),
-						'query_key' => $from_query_type,
-						'type' => $from_query_type,
-					]
-				);
+			if ( self::SEARCH_QUERY_KEY === $from_query_type && ! isset( $from_input_schema['search_terms'] ) ) {
+				return self::create_error( $block_title, 'A search query must have a "search_terms" input variable' );
 			}
+
+			// Add the selector to the configuration.
+			array_unshift(
+				$config['selectors'],
+				[
+					'image_url' => $from_query->get_image_url(),
+					'inputs' => [],
+					'name' => $selection_query['display_name'] ?? ucfirst( $from_query_type ),
+					'query_key' => $from_query::class,
+					'type' => $from_query_type,
+				]
+			);
 		}
 
 		// Register query input overrides which allow the user to specify how
 		// query inputs can be overridden by URL parameters or query variables.
-		foreach ( $user_config['query_input_overrides'] ?? [] as $override ) {
-			if ( ! isset( $config['queries'][ $override['query'] ] ) ) {
-				return self::create_error( $block_title, sprintf( 'Query input override targets a non-existent query "%s"', esc_html( $override['query'] ) ) );
-			}
-
+		foreach ( $user_config[ self::RENDER_QUERY_KEY ]['input_overrides'] ?? [] as $override ) {
 			if ( 'input_var' !== $override['target_type'] ) {
 				return self::create_error( $block_title, 'Only input variables can be targeted by query input overrides' );
 			}
 
-			if ( ! isset( $config['queries'][ $override['query'] ]->get_input_schema()[ $override['target'] ] ) ) {
-				return self::create_error( $block_title, sprintf( 'Query input override "%s" does not exist as input variable for query "%s"', esc_html( $override['target'] ), esc_html( $override['query'] ) ) );
+			if ( ! isset( $input_schema[ $override['target'] ] ) ) {
+				return self::create_error( $block_title, sprintf( 'Input override "%s" does not exist as input variable for render query', esc_html( $override['target'] ) ) );
 			}
 
 			$config['query_input_overrides'][] = $override;
@@ -196,11 +193,11 @@ private static function register_block_pattern( string $block_name, string $patt
 	 */
 	private static function register_page( array $query_input_overrides, string $block_title, array $options = [] ): bool|WP_Error {
 		$overrides = array_values( array_filter( $query_input_overrides, function ( $override ) {
-			return 'page' === $override['source_type'] && ConfigRegistry::DISPLAY_QUERY_KEY === $override['query'];
+			return 'page' === $override['source_type'];
 		} ) );
 
 		if ( empty( $overrides ) ) {
-			return new WP_Error( 'useless_page', 'A page is only useful with query input overrides with page sources.' );
+			return new WP_Error( 'useless_page', 'A page is only useful when there are query input overrides with page sources.' );
 		}
 
 		$allow_nested_paths = $options['allow_nested_paths'] ?? false;

diff --git a/inc/ExampleApi/ExampleApi.php b/inc/ExampleApi/ExampleApi.php
@@ -116,9 +116,14 @@ public static function register_remote_data_block(): void {
 
 		register_remote_data_block( [
 			'title' => self::$block_title,
-			'queries' => [
-				'display' => $get_record_query,
-				'list' => $get_table_query,
+			'render_query' => [
+				'query' => $get_record_query,
+			],
+			'selection_queries' => [
+				[
+					'query' => $get_table_query,
+					'type' => 'list',
+				],
 			],
 		] );
 	}

diff --git a/inc/Integrations/Airtable/AirtableIntegration.php b/inc/Integrations/Airtable/AirtableIntegration.php
@@ -19,9 +19,14 @@ public static function register_block_for_airtable_data_source( AirtableDataSour
 			array_merge(
 				[
 					'title' => $data_source->get_display_name(),
-					'queries' => [
-						'display' => $data_source->___temp_get_query(),
-						'list' => $data_source->___temp_get_list_query(),
+					'render_query' => [
+						'query' => $data_source->___temp_get_query(),
+					],
+					'selection_queries' => [
+						[
+							'query' => $data_source->___temp_get_list_query(),
+							'type' => 'list',
+						],
 					],
 				],
 				$block_overrides
@@ -34,9 +39,9 @@ public static function register_loop_block_for_airtable_data_source( AirtableDat
 			array_merge(
 				[
 					'title' => sprintf( '%s Loop', $data_source->get_display_name() ),
-					'loop' => true,
-					'queries' => [
-						'display' => $data_source->___temp_get_list_query(),
+					'render_query' => [
+						'loop' => true,
+						'query' => $data_source->___temp_get_list_query(),
 					],
 				],
 				$block_overrides

diff --git a/inc/Integrations/SalesforceB2C/SalesforceB2CIntegration.php b/inc/Integrations/SalesforceB2C/SalesforceB2CIntegration.php
@@ -138,17 +138,26 @@ private static function get_queries( SalesforceB2CDataSource $data_source ): arr
 	}
 
 	public static function register_blocks_for_salesforce_data_source( SalesforceB2CDataSource $data_source ): void {
+		$queries = self::get_queries( $data_source );
+
 		register_remote_data_block(
 			[
 				'title' => $data_source->get_display_name(),
-				'queries' => self::get_queries( $data_source ),
-				'query_input_overrides' => [
+				'render_query' => [
+					'query' => $queries['display'],
+					'input_overrides' => [
+						[
+							'source' => 'utm_content',
+							'source_type' => 'query_var',
+							'target' => 'product_id',
+							'target_type' => 'input_var',
+						],
+					],
+				],
+				'selection_queries' => [
 					[
-						'query' => 'display',
-						'source' => 'utm_content',
-						'source_type' => 'query_var',
-						'target' => 'product_id',
-						'target_type' => 'input_var',
+						'query' => $queries['search'],
+						'type' => 'search',
 					],
 				],
 			]

diff --git a/inc/Integrations/Shopify/ShopifyIntegration.php b/inc/Integrations/Shopify/ShopifyIntegration.php
@@ -114,9 +114,14 @@ public static function register_blocks_for_shopify_data_source( ShopifyDataSourc
 
 		register_remote_data_block( [
 			'title' => $block_title,
-			'queries' => [
-				'display' => $queries['shopify_get_product'],
-				'search' => $queries['shopify_search_products'],
+			'render_query' => [
+				'query' => $queries['shopify_get_product'],
+			],
+			'selection_queries' => [
+				[
+					'query' => $queries['shopify_search_products'],
+					'type' => 'search',
+				],
 			],
 			'patterns' => [
 				[