Block Hooks: Iteration for WP 6.6

[ockham]

• Part of Block API #41236.
• Supersedes Epic: Block Hooks Features for WP 6.5 #54904.

Block Hooks have been formerly know as Auto-inserting Blocks.

Plans for WordPress 6.6

The following is a list of issues and tickets planned for WP 6.5, roughly ordered by priority (and/or order in which we should tackle them for practical reasons).

Named Block Variations

• Blocks: Add support for block name aliases for variations #43743
  • One major Block Hooks-adjacent focus for 6.5 will be to explore named block variations on the server side. This should enable us to use a block variation alias as a block type name in the context of Block Hooks (e.g. for ignoredHookedBlocks) in order to allow insertion of "generic blocks", i.e. multiple blocks of the same type that are only distinguished by the values of (a subset of) their attributes.
  • For some related discussion and background, see Block Hooks API: Add hooked_blocks filter to allow hooked block extensibility wordpress-develop#6228 (comment).

UX bugs

• #59574: No toggle shown for hooked blocks added via filter (unless the containing template/part/... has been modified by the user)
  • Block Hooks API: Insert metadata at the same time as hooked blocks wordpress-develop#6358
• #60756: Toggle (re-)inserts hooked block in wrong position (if added by filter)

Code quality

• #60759: Harmonize ignoredHookedBlocks metadata injection logic
  • This is a (soft) prerequisite for hooked block insertion into Template Part blocks (as first/last child, #60854) and into Post Content (#61074) (see below).
• #60769: Consolidate approach to get the list of hooked blocks
  • This has been a long-standing annoyance. Fixing it will make maintaining and extending the Block Hooks codebase a lot easier.

DX improvements

• #60854: Allow insertion as first or last child of Template Part block (WP 6.7)
• #61074: Enable for post content
  • Can be implemented in user code (by using the the_content and corresponding REST API endpoint filters), see e.g. POC: Block Hooks API: Cart and Checkout Integration woocommerce/woocommerce#46859
• #60906: Allow adding toggle without injecting hooked block

---

For later releases

DX improvements

• Provide containing context. Currently, we're only providing the immediately containing context (e.g. the containing template part). If a user would like to conditionally insert a hooked block based on context that's further up the hierarchy (e.g. the template that contains the template part), this is currently impossible.
• #61078: Consider introducing a dedicated endpoint.

UX improvements

• Block Hooks: Add UI to inform user about newly added hooked blocks #60369

Performance

• Block Hooks: Process blocks more efficiently. wordpress-develop#5753
  • This would replace parse_blocks/traverse_and_serialize_blocks by a streaming parser.

Uncategorized

• Block Hooks: Respect allowedBlocks field and control for users #53989
  • Originally touched upon here. We might want to give a block some level of control what blocks it allows as its (auto-inserted) children.
  • There's an allowedBlock attribute that's currently used by a number of blocks; AFAICT, it's only handled on the client side, and basically passed through to the InnerBlocks component as a prop. I'm a bit hesitant to use something like this as it seems currently really up to each individual block, with no standardization, especially on the server (e.g. in the shape of block-supports).
  • Implementing this later might amount to an API change: Blocks that were previously auto-inserted might cease to be if their parent disallows them 😕
• Respect template locks.
  • I need to read up on them, but I imagine we shouldn't auto-insert into a locked template? 😬
• Respect "multiple": false.
  • Blocks can stipulate they only be inserted once. Auto-insertion should probably respect that; @nerrad made a PoC PR during WCUS Contributor Day: Rough POC of respecting "supports multiple" in the auto-inserted block metadata #53925
  • Some prior discussion: "It could also be that autoInsert works upon the first encountered block of the specified type, so it doesn't get repeated if there are multiple navigation blocks in a page. Or maybe this is also a flag like useOnce."
  • This still doesn't give control over which navigation block that is (but will default to the first one encountered); we might want a mechanism to select that, too. See next item for a somewhat related problem.
  • Finally, note that the multiple field was originally introduced for a post editor context; it isn't really well-defined in a template/Site Editor, as @gziolo has observed.
• #60852: Make conditional tags work when processing content for REST API Closed as WONTFIX, see this comment.
  • Note that getting is_singular() to work would allow users to inject a hooked block only when the current template is for a custom post type (e.g. if ( is_singular( 'book' ) ) { /* ... */ }), which seems to be a recurring request.

[ockham]

Finally replying to @leewillis77's comment on the previous Epic -- apologies for the long delay!

I'd echo the sentiment in #54904 (comment). For plugins to work reliably and effectively having a full chain of context would definitely be desirable so that we can do things like "insert block X after block Y whenever it appears inside block Z" even when Y isn't necessarily a direct descendent of Z. As well as being more robust, in many cases it would also simplify development.

Right. Unfortunately, providing a full chain of context seems to be a bit tricky to implement right now, as WordPress doesn't currently communicate the parent to the child block upon stepping into the latter processing. (This is exacerbated by a number of blocks rendering their own, "detached", block trees, e.g. the Template Part or Navigation blocks.)

I have to look into this a bit more deeply and might file a Core ticket.

Working out the combination of anchor/context that should be used to insert at a given location is more complex than it feels like it should be as the registration covers all registered items, and there's no way (that I could work out) to see what anchor/contexts are triggered on a given page. Not sure what the solution is here, maybe it would be less of an issue if [1] was solved?

So If you're writing a filter for the hooked_block_types hook, or the newly introduced hooked_block/hooked_block_{$hooked_block_type} ones, it's best to start with very loose criteria for block insertion. I'd suggest ignoring $context altogether at first, and only limiting by anchor block and position (e.g. if ( 'after' === $relative_position && 'core/post-content' === $anchor_block_type ) { ... }), as this will insert the hooked block regardless of context.

Once you've got that working, you can add criteria for $context as well. To get a better idea of what it looks like, you can do some "poor dev's debugging" by adding e.g. a print_r ( $context ) to your filter.

BTW have you seen @ndiego's recent Developer Blog article on Block Hooks? It's a great way to get started (and also includes recommendations like the above) 😄

Block hooks are only truly useful if they can be used to reliably insert blocks into other blocks. At the minute there are some situations where it can be used, and others where it can't. As an example, take the WooCommerce 'product collection' block. Block hooks can be used to register blocks into this if the user selects a template, but the hook doesn't take any effect for the default block insertion, which leads to a confusing developer experience, and an inconsistent user experience.

I think this largely harks back to a problem I touched upon in my reply to your first request: There are a number of container blocks that include "controlled" inner blocks (that are fetched from the DB, rather than being included "inline" in the markup), and to make those work, each of them must basically opt into the Block Hooks mechanism by applying it in its render method. For WP 6.5, we've done that for Core's Navigation block; the solution we came up with for that block might be applicable to a number of other parts, both Core and 3rd party.

[ockham]

I've updated the issue to list the items we're targeting for 6.6. The "headliner" feature is now named block variations, as this seems to be a blocker for the one feature that we're having the strongest demand for (i.e., generic block insertion). The rest is largely smaller UX/DX fixes, some of which depend on some code quality improvements.

As I'll be AFK for the next two weeks, @tjcafferkey will take the reins for #43743. Upon my return, we'll evaluate if we can reasonably get something done in time for 6.6; otherwise, we'll likely focus on the smaller improvements instead.

cc/ @gziolo @joshuatf @nerrad

[fabiankaegy]

Hi all 👋

Reminder: The release candidate for Gutenberg Version 18.5 is scheduled for next Friday (May 31st). So anything that is supposed to make it into WordPress 6.6 must be merged by then.

Please raise any important issues that need additional attention :)

[ockham]

Update (for Block Hooks specific stuff; I'll post a separate update on Block Variations to the corresponding issue):

I've committed @tjcafferkey's fix that shows the toggle for hooked blocks that were added by a filter to an _un_modified template. Tom has also filed a fix for the harmonization for the ignoredHookedBlocks metadata injection logic and a Gutenberg counterpart. Both are good to go; we'll have to merge the GB PR first and then wait for packages to be synced before we can land the Core change.

Tom has also started work on consolidating how we get the list of hooked blocks. This is a bit of a trickier problem, due to the way we check the result of get_hooked_blocks early on to avoid parsing/traversing/reserializing the block tree if there aren't any hooked blocks; this gets in the way of deprecating that function in favor of a more context-aware one (that also applies the hooked_block_types filter), as the latter can only be run on individual tree nodes (i.e. blocks), rather than on the entire block tree.

Given time, we're unlikely to tackle any other Block Hooks related issues for 6.6 (possibly with the exception of moving some more code from the Navigation block into Core, to fully resolve #60759); instead, we'll be focusing on Block Variations.

[gziolo]

The work on WordPress 6.6 has wrapped up. @ockham, what are the next steps for this iteration issue? Do you think we should close it?

[ockham]

Yes, I think it's fine to close, especially now that it's decided that we aren't going to pursue #43743 (except for variation className block support).

I'll triage the remaining open issues and we can decide what to do with them. (Due to another project and some AFK time, I might only get around to doing that in about three weeks from now 😬)