Block registration

Use the register_remote_data_block function to register your remote data block and associate it with your query and data source. This example:

1. Creates a data source.
2. Associates the data source with a query.
3. Defines the output schema of a query, which tells the plugin how to map the query response to blocks.
4. Registers a remote data block.

We are assuming https://api.example.com/ returns JSON that has a shape like:

{
	"id": 12345,
	"title": "An awesome title"
}

function register_your_custom_block() {
	$data_source = [
		'display_name' => 'Example API',
		'endpoint' => 'https://api.example.com/',
	];

	$render_query = [
		'display_name' => 'Example Query',
		'data_source' => $data_source,
		'output_schema' => [
			'type' => [
				'id' => [
					'name' => 'ID',
					'path' => '$.id',
					'type' => 'id',
				],
				'title' => [
					'name' => 'Title',
					'path' => '$.title',
					'type' => 'string',
				],
			],
		],
	];

	register_remote_data_block( [
		'title' => 'My Block',
		'render_query' => [
			'query' => $render_query,
		],
	] );
}
add_action( 'init', 'register_your_custom_block', 10, 0 );

The human-friendly name of the block. It is also used to construct the block’s name; a title of “My Block” will result in a block name of remote-data-blocks/my-block.

The render query is executed when the block is rendered and fetches the data that will be provided to block bindings. It is an array with the following properties:

• query (required): An instance of QueryInterface that fetches the data.

Selection queries are used by content creators to select or curate remote data in the block editor. For example, you may wish to provide a list of products to users and allow them to select one to include in their post, or you may want to allow a user to search for a specific item. Selection queries are an array of objects with the following properties:

• display_name: A human-friendly name for the selection query.
• query (required): An instance of QueryInterface that fetches the data.
• type: A string that determines the type of selection query. Accepted values are currently list or search.

Example:

'selection_queries' => [
    [
        'display_name' => 'Select a product',
        'query' => $list_products_query,
        'type' => 'list',
    ],
    [
        'display_name' => 'Search for a product',
        'query' => $search_products_query,
        'type' => 'search',
    ],
],

Search queries must return a collection and must accept an input variable with the special type ui:search_input. The Art block example looks like this:

$search_art_query = [
	'data_source' => $aic_data_source,
	'endpoint' => function ( array $input_variables ) use ( $aic_data_source ): string {
		$query = $input_variables['search'];
		$endpoint = $aic_data_source->get_endpoint() . '/search';

		return add_query_arg( [ 'q' => $query ], $endpoint );
	},
	'input_schema' => [
		'search' => [
			'name' => 'Search terms',
			'type' => 'ui:search_input',
		],
	],
	'output_schema' => [
		'is_collection' => true,
		'path' => '$.data[*]',
		'type' => [
			'id' => [
				'name' => 'Art ID',
				'type' => 'id',
			],
			'title' => [
				'name' => 'Title',
				'type' => 'string',
			],
		],
	],
];

Here you can see the search input variable has a special type of ui:search_input and is used in the endpoint method to populate a query string. You can read more about queries and how to construct them. End users enter the search term to find the specific item.

Note: The same search box appears for list query types. For this type, the form is only filtering the results returned by the initial list query. For search queries, an additional query is made for every search.

Overrides are used to customize the behavior of the block on a per-block basis.

Block patterns allow you to customize the display of your remote data.