Blocks: Insert hooked blocks #5261

ockham · 2023-09-20T13:04:52Z

Synopsis

This feature is meant to provide an extensibility mechanism for Block Themes, in analogy to WordPress' Hooks concept that has allowed extending Classic Themes through filters and actions.

Specifically, Block Hooks allow a third-party block to specify a position relative to a given block into which it will then be automatically inserted (e.g. a "Like" button block can ask to be inserted after the Post Content block, or an eCommerce shopping cart block can ask to be inserted after the Navigation block).

The two core tenets for block hooks are:

Insertion into the frontend should happen right after a plugin containing a hooked block is activated (i.e. the user isn't required to insert the block manually in the editor first); similarly, disabling the plugin should remove the hooked block from the frontend.
The user has the ultimate power to customize that automatic insertion: The hooked block is also visible in the editor, and the user's decision to persist, dismiss, customize, or move it will be respected (and reflected on the frontend).

To account for both tenets, we've made the tradeoff that automatic block insertion only works for unmodified templates (and template parts, respectively). The reason for this is that the simplest way of storing the information whether a block has been persisted to (or dismissed from) a given template (or part) is right in the template markup. This was first suggested here.

To accommodate for that tradeoff, we've added UI controls (toggles) to increase visibility of hooked blocks, and to allow their later insertion into templates (or parts) that already have been modified by the user.

Implementation

Since we wanted hooked blocks to appear both in the frontend and in the editor (see tenet number 2), we had to make sure they were inserted into both the frontend markup and the REST API (templates and patterns endpoints) equally. As a consequence, this means that automatic insertion couldn't only be implemented at block render stage, as for the editor, we needed to modify the serialized (but unrendered) markup.

However, thanks to the tradeoff we made (see above), we could at least limit ourselves to only inserting hooked blocks into unmodified templates (and parts), i.e. those that were coming directly from a Block Theme's template (or parts) file, rather than the database, and patterns.

It turns out that there's a rather natural stage for automatic insertion of hooked blocks to happen, which is during template file retrieval (and loading of patterns, respectively).

Trac ticket: https://core.trac.wordpress.org/ticket/59313

Supersedes #5158.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

ockham · 2023-09-20T18:13:13Z

@gziolo I'm hoping that this PR will become the final piece to implement Block Hooks. It should be pretty much feature-complete if I didn't miss anything 🙂

src/wp-includes/blocks.php

gziolo · 2023-09-21T08:52:45Z

src/wp-includes/blocks.php

+
+		if ( $parent && ! $prev ) {
+			// Candidate for first-child insertion.
+			$hooked_blocks_for_parent = get_hooked_blocks( $parent['blockName'] );


get_hooked_blocks is going to be called too many times. I will work on some optimizations tomorrow.

ockham · 2023-09-21T10:07:13Z

Weird, unit tests are currently failing:

Invalid argument supplied for foreach()

/var/www/src/wp-includes/blocks.php:754

That's this line:

wordpress-develop/src/wp-includes/blocks.php

Line 754 in aa033cb

    
           foreach ( $block_type->block_hooks as $anchor_block_type => $relative_position ) {

I wonder if/why the block_hooks field isn't available at all (rather than defaulting to the empty array)?

ockham · 2023-09-21T10:09:34Z

Workaround in bd1c57b. Let's see if that works.

src/wp-includes/blocks.php

gziolo · 2023-09-21T11:30:43Z

src/wp-includes/blocks.php

@@ -751,6 +751,9 @@ function get_hooked_blocks( $name ) {
 	$block_types = WP_Block_Type_Registry::get_instance()->get_all_registered();
 	$hooked_blocks = array();
 	foreach ( $block_types as $block_type ) {
+		if ( ! property_exists( $block_type, 'block_hooks' ) ) {


I wonder if/why the block_hooks field isn't available at all (rather than defaulting to the empty array)?

It might be the tests for REST API that try to inject invalid values. ! empty( $block_type->block_hooks ) check would be faster and it would also cover the case when there is an empty array.

It might be an issue with the missing test clean up. I'm trying unregistering the block with invalid data: d783702.

ockham · 2023-09-21T11:56:24Z

Seeing the same test failure I had earlier:

Invalid argument supplied for foreach()

/var/www/src/wp-includes/blocks.php:757

Maybe I need to add an is_array check alongside property_exists.

ockham · 2023-09-21T11:57:29Z

Seeing the same test failure I had earlier:
Invalid argument supplied for foreach()

/var/www/src/wp-includes/blocks.php:757
Maybe I need to add an is_array check alongside property_exists.

22c75d9

gziolo

We still need to increase the code coverage with unit tests, but overall, it works as expected based on the smoke tests performed. I'm very confident that traverse_and_serialize_blocks is implemented correctly. Some follow-up work will require:

Increased test coverage for make_before_block_visitor and make_after_block_visitor (they are tested indirectly to some degree).
Integration test for Block Hooks that spans a simplified theme based on Twenty Twenty-Three that contains template file with a template part and pattern sourced from the theme folders.
Performance audit for get_hooked_blocks and potentially also to traverse_and_serialize_blocks.

ockham · 2023-09-21T15:58:07Z

Thanks a lot for the test coverage @gziolo, I quite like your approach! 😄

Block Hooks allow a third-party block to specify a position relative to a given block into which it will then be automatically inserted (e.g. a "Like" button block can ask to be inserted after the Post Content block, or an eCommerce shopping cart block can ask to be inserted after the Navigation block). The underlying idea is to provide an extensibility mechanism for Block Themes, in analogy to WordPress' [https://developer.wordpress.org/plugins/hooks/ Hooks] concept that has allowed extending Classic Themes through filters and actions. The two core tenets for Block Hooks are: 1. Insertion into the frontend should happen right after a plugin containing a hooked block is activated (i.e. the user isn't required to insert the block manually in the editor first); similarly, disabling the plugin should remove the hooked block from the frontend. 2. The user has the ultimate power to customize that automatic insertion: The hooked block is also visible in the editor, and the user's decision to persist, dismiss (i.e. remove), customize, or move it will be respected (and reflected on the frontend). To account for both tenets, the **tradeoff** was made to limit automatic block insertion to unmodified templates (and template parts, respectively). The reason for this is that the simplest way of storing the information whether a block has been persisted to (or dismissed from) a given template (or part) is right in the template markup. To accommodate for that tradeoff, [WordPress/gutenberg#52969 UI controls (toggles)] are being added to increase visibility of hooked blocks, and to allow for their later insertion into templates (or parts) that already have been modified by the user. For hooked blocks to appear both in the frontend and in the editor (see tenet number 2), they need to be inserted into both the frontend markup and the REST API (templates and patterns endpoints) equally. As a consequence, this means that automatic insertion couldn't (only) be implemented at block ''render'' stage, as for the editor, the ''serialized'' (but ''unrendered'') markup needs to be modified. Furthermore, hooked blocks also have to be inserted into block patterns. Since practically no filters exist for the patterns registry, this has to be done in the registry's `get_registered` and `get_all_registered` methods. Props gziolo. Fixes #59313.

ockham · 2023-09-21T16:17:12Z

Committed to Core in https://core.trac.wordpress.org/changeset/56649.

ockham self-assigned this Sep 20, 2023

ockham mentioned this pull request Sep 20, 2023

Blocks: Add post-block callback arg to traverse_and_serialize_block(), change signature #5257

Closed

ockham force-pushed the try/block-hooks branch from dd36c2f to d3d8e08 Compare September 20, 2023 16:50

ockham changed the title ~~Demonstrate new block insertion technique~~ Blocks: Insert hooked blocks Sep 20, 2023

ockham commented Sep 20, 2023

View reviewed changes

src/wp-includes/blocks.php Outdated Show resolved Hide resolved

gziolo reviewed Sep 21, 2023

View reviewed changes

src/wp-includes/blocks.php Outdated Show resolved Hide resolved

src/wp-includes/blocks.php Outdated Show resolved Hide resolved

src/wp-includes/blocks.php Outdated Show resolved Hide resolved

ockham force-pushed the try/block-hooks branch from 70b85fe to 6514caa Compare September 21, 2023 08:42

ockham mentioned this pull request Sep 21, 2023

Add Block Hooks (a.k.a. Auto-inserting Blocks) #5158

Closed

gziolo reviewed Sep 21, 2023

View reviewed changes

ockham commented Sep 21, 2023

View reviewed changes

src/wp-includes/blocks.php Outdated Show resolved Hide resolved

gziolo reviewed Sep 21, 2023

View reviewed changes

gziolo approved these changes Sep 21, 2023

View reviewed changes

ockham marked this pull request as ready for review September 21, 2023 15:40

ockham force-pushed the try/block-hooks branch from f6ad79a to 57d7a15 Compare September 21, 2023 16:14

ockham closed this Sep 21, 2023

ockham deleted the try/block-hooks branch September 21, 2023 16:17

ockham mentioned this pull request Oct 4, 2023

Patterns: Insert hooked blocks upon registration #5406

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Blocks: Insert hooked blocks #5261

Blocks: Insert hooked blocks #5261

ockham commented Sep 20, 2023 •

edited

Loading

ockham commented Sep 20, 2023

gziolo Sep 21, 2023

ockham commented Sep 21, 2023

ockham commented Sep 21, 2023

gziolo Sep 21, 2023

gziolo Sep 21, 2023

ockham commented Sep 21, 2023

ockham commented Sep 21, 2023

gziolo left a comment

ockham commented Sep 21, 2023

ockham commented Sep 21, 2023

Blocks: Insert hooked blocks #5261

Blocks: Insert hooked blocks #5261

Conversation

ockham commented Sep 20, 2023 • edited Loading

Synopsis

Implementation

ockham commented Sep 20, 2023

gziolo Sep 21, 2023

Choose a reason for hiding this comment

ockham commented Sep 21, 2023

ockham commented Sep 21, 2023

gziolo Sep 21, 2023

Choose a reason for hiding this comment

gziolo Sep 21, 2023

Choose a reason for hiding this comment

ockham commented Sep 21, 2023

ockham commented Sep 21, 2023

gziolo left a comment

Choose a reason for hiding this comment

ockham commented Sep 21, 2023

ockham commented Sep 21, 2023

ockham commented Sep 20, 2023 •

edited

Loading