Include Block Hooks in WordPress 6.4

[ockham]

• Part of Block API #41236.

Block Hooks are formerly know as Auto-inserting Blocks.

We've merged a basic version of auto-inserting blocks in #51449, and are currently working on adding UI controls in #52969. Generally, we seem to be on track for inclusion of this new feature in WordPress 6.4, whose feature freeze is on September 26 -- a little less than a month from now.

We've previously discussed auto-inserting blocks in #39439, which has also served as a tracking issue of sorts. I think it's time to close that issue in favor of a new tracking issue for the remaining tasks for inclusion in WP 6.4.

For Gutenberg 16.6.0

RC1: August 30
Stable release: September 6

• Auto-inserting blocks: Add block inspector panel #52969 (Adress feedback, merge.)
• Auto-inserting blocks: Remove toggle if block is present elsewhere #54024
• Auto-inserting blocks: Add block icon to block inspector panel toggles #54029
• Rename "auto inserting blocks" to "block hooks" #54147

For Gutenberg 16.7.0

RC1: September 20. Last Gutenberg version to be included in WP 6.4!

• Block Hooks: Incorrect placement in the parent container for hooked blocks #54307 that will get fixed with Blocks: Fix incorrect placement for hooked blocks in the parent container #54349.
• Make sure the panel doesn't show up outside of Site Editor - it happens in the Post Editor.
• Remove __experimental status (Block API: Stabilize Block Hooks feature #54293).
• Plugin: Ensure that Block Hooks work correctly after landing in WP core #54651

For WordPress 6.4

Feature Freeze: September 26

• Port PHP code to Core.
• Allow limiting auto-insertion by template type/template part type/post type etc. (Done in Blocks: Insert hooked blocks wordpress-develop#5261.)
  • This is a feature that most people basically request the moment they learn about auto-inserting blocks; I've most recently discussed it with @nerrad at the WCUS Contributor Day. IIRC, @mtias was somewhat skeptical about prioritizing a syntax in block.json for this.
  • One idea we've been discussing was some kind of filter. I'm happy to give that a try; one downside I see is that we'd fragment the API for auto-insertion a bit, by allowing specifying the anchor block and relative position in block.json, but only programmatically allowing limiting to certain template types etc.
  • The function signature I have in mind would at a minimum pass the current template type/template part type to the filter; maybe also the number of blocks that have already been inserted into the same template (see previous item). It might work similar to some of Core's pre_-prefixed filters that allow short-circuiting an operation (to avoid auto-insertion, in this case).
• Blocks: Introduce filter to allow easy addition of hooked blocks wordpress-develop#5271
• Blocks: Remove inject_hooked_block_markup filter wordpress-develop#5292
• Blocks: Add more unit test covering edge cases for Block Hooks wordpress-develop#5279
• Blocks: Change get_hooked_blocks() to returned hooked blocks grouped by relative position wordpress-develop#5297
• Templates: Deprecate _inject_theme_attribute_in_block_template_content(). wordpress-develop#5307
• Templates: Move old theme attr injection function to deprecated.php wordpress-develop#5317
• Templates: Introduce _remove_theme_attribute_from_template_part_block function wordpress-develop#5316
• Patterns: Add test coverage for patterns registry wordpress-develop#5299
• REST API: Improve the block type schema for the name field wordpress-develop#5278

Later

See #54904.

---

I'd say the above list sounds ambitious 😅 but not all items I've listed might be hard requirements for WP 6.4; keeping some of them for later will greatly reduce the workload. I'd be curious to hear y'all's thoughts on which ones you think should definitely go into 6.4.

The biggest risk IMO is currently the limitation to certain template types/post types, especially if we'd like to have syntax in block.json to accommodate for that (and not lock down the autoInsert field to a more basic syntax already). If we'd like to tackle that for WP 6.4, I could use a hand working on that 😬 @gziolo How's your availability in the next couple of weeks? 😅

It'd be great to give the feature some extended user testing once the block inspector panel lands (i.e. GB 16.6). @annezazu Is that something you could help with (or can you point me to someone else if your plate is full enough already)?

We'll need to eventually remove __experimental status, and add the autoInsert field to the block.json schema. Ideally, I'd like to give it a bit more time and only do so in time for 16.7 RC1 (which is the final version for inclusion in WP 6.4 if I'm not mistaken); please LMK if y'all feel that we should already do so for GB 16.6.

cc/ @priethor @mtias for feedback/project planning/general visibility 😄

[draganescu]

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).

The navigation block uses the blocks in allowed blocks list to build the correct markup for the list items of submenus. This will lead to bad markup rendered if the block to be renderer is not in that list. I've proposed in other places as well that we raise allowed blocks from an inner blocks prop to something that comes from block.json and it sounds very close to:

We might want to give a block some level of control what blocks it allows as its (auto-inserted) children.

[mtias]

I've seen anecdotal feedback that autoInsert is not the clearest of descriptions. I'd like to propose renaming to the more familiar hooks terminology—and "block hooks" in more general terms—to help folks understand the mechanics and purpose more rapidly.

[annezazu]

It'd be great to give the feature some extended user testing once the block inspector panel lands (i.e. GB 16.6). @annezazu Is that something you could help with (or can you point me to someone else if your plate is full enough already)?

Happy to explore what this might look like, especially since I'm holding off until likely 16.6 RC1 or the full release to do the next call for testing at this point. From everything I know about this, we would need a plugin installed to simulate an auto-insertion. Is that correct? If so, do we have any that currently work with this functionality? That's the biggest hurdle.

[ockham]

It'd be great to give the feature some extended user testing once the block inspector panel lands (i.e. GB 16.6). @annezazu Is that something you could help with (or can you point me to someone else if your plate is full enough already)?

Happy to explore what this might look like, especially since I'm holding off until likely 16.6 RC1 or the full release to do the next call for testing at this point.

Amazing, thank you!

From everything I know about this, we would need a plugin installed to simulate an auto-insertion. Is that correct? If so, do we have any that currently work with this functionality? That's the biggest hurdle.

I wrote a small "Like button" block plugin for testing that auto-inserts the block as every Comment Template block's last child.

FWIW, making a dynamic block auto-insert itself is as easy as adding a couple of lines to its block.json. E.g. I managed to make WC Blocks' Mini Cart block auto-insert itself after the Navigation menu by adding the following to its block.json:

"__experimentalAutoInsert": {
        "core/navigation": "after"
}

[annezazu]

That works great. We can use the "like button" for the testing :)

[ndiego]

@ockham I just wanted to note that I’m planning an article for the WordPress Developer Blog to prep folks for this functionality in 6.4.

[sethrubenstein]

@ndiego That would be very helpful. I'm hoping to parlay this work into allowing theme developers to specify what the "default block" on the navigation block #52610 (comment). A primer would be very helpful to get me caught up on this new api.

[ockham]

Update:

I've merged PRs #54024 (remove the toggle if the block is present elsewhere in the tree and thus presumed manually inserted) and #54029 (add the block icons, right-align toggles) and cherry-picked them to GB 16.6.

Can I get a quick check on priorities for GB 16.6 (due on Wednesday) @mtias @annezazu @ndiego? I've got three candidates that might make sense to squeeze in IMO:

• Rename feature to "block hooks": Might make sense to rename already so that user testing will happen based on the new/final name (I already started work on this one, but I'm happy to punt.)
• Remove __experimental flag: Might make sense for a similar reason -- in order for the feature to be exposed as stable for a bit of time before WP 6.4. (Pretty sure we should rename first though -- we don't want to stabilize a name and block.json field that we know we'll have to change afterwards!)
• Add a filter to allow limiting to a given template type/template part type/post type. There's currently no way to do that, even though it's pretty much the number one request I'm getting from everyone testing the feature. I think we want this in WP 6.4 -- is it enough to add it only after GB 16.6 ships? (I.e. in time for GB 16.7 RC1.)

I'm not sure I have enough time to handle all three by Wednesday, so we'll need to prioritize 😬

[gziolo]

@ockham, that is an excellent summary regarding the current status of the feature. Everything is still behind the feature, so I personally don't think we have to rush all things for Wednesday this week, but it would be great to change the UI part at least. I do think, we should follow what the release squad thinks and I'm happy to help.

Add a filter to allow limiting to a given template type/template part type/post type. There's currently no way to do that, even though it's pretty much the number one request I'm getting from everyone testing the feature. I think we want this in WP 6.4 -- is it enough to add it only after GB 16.6 ships? (I.e,. in time for GB 16.7 RC1.)

I'd love to have that shipped in WordPress 6.4. The reason for that is we won't have to support too many advanced use cases initially, but instead we will be able to drive future iterations based on the most common use cases that extenders should be able to achieve by leveraging WP hooks. The nice side-effect of making the API extensible is that we should also have a backdoor for adding first-class support for integrations between Auto-inserting Blocks with other existing APIs like parent, ancestororsupports.multiple` (related PR #53925). It might turn out we would have to offer PHP and JS versions of the same filter that is able to change the result of the logic that decides whether a block should get auto-inserted in a certain circumstance.

[mtias]

@mtias was somewhat skeptical about prioritizing a syntax in block.json for this.

There's a few reasons to not overload the block.json syntax—for one, blocks can be used outside of WordPress, and while the concept of hooks and placement is widely relevant, context is not. It's going to be more flexible to leverage the full server context to conditionally manipulate the block hook attribute as needed through filters.

[ockham]

Add a filter to allow limiting to a given template type/template part type/post type. There's currently no way to do that, even though it's pretty much the number one request I'm getting from everyone testing the feature. I think we want this in WP 6.4 -- is it enough to add it only after GB 16.6 ships? (I.e. in time for GB 16.7 RC1.)

Update on this item: I've thought about this for a while now, and I think there's a bit of a risk that I might end up designing a solution for this that's shaped by the current implementation of auto-inserting blocks (a.k.a block hooks) inside of GB -- which makes heavy use of filters in order to inject logic that inserts blocks in their designated positions.

I'm starting to think that it'll be better to port the existing code to Core first (which will likely include some architectural decisions on where to best put some of the logic), and only then to add a mechanism (likely a filter) to limit blocks insertion to certain templates and/or template parts. (This means that we wouldn't be able to test that mechanism as part of a GB release, but only once WP 6.4 Beta 1 is out.) Since we're running out of time for GB 16.6 anyway and any filter mechanism will require a bit more thought anyway, I'm inclined to embrace this.

[Ren2049]

Sorry if it's a silly question, but would it be possible to create a rule for the post content blocks where a certain pattern is inserted e.g. after a certain amount of paragraphs or every x amount of paragraphs? Could be a cool plugin-less way to manage ads with synced patterns, or to add a table of contents block as part of a template but within the post content.

[gziolo]

I spent some time reviewing existing Block API features that might make people think they should intersect with how auto-inserting blocks work. Here is the summary of what I found out.

parent

The current definition in the handbook:

Theoretically, it's fully compatible when the block gets inserted after or before the block, as it would be an additional requirement. Things become complicated when processing firstChild and lastChild as both explicitly define the allowed parent block, so using parent in that case seems redundant. However, I can imagine situations where the block's author doesn't want to restrict where the block gets inserted through the UI, or they allow multiple parent blocks when using the inserter. The related concern is what happens when the parent block restricts in JavaScript what are the allowed inner blocks. I don't think we can intercept that information in PHP, but at the same time, if I remember correctly, parent takes precedence over allowed inner blocks 🤷🏻

Technically speaking, we could respect the parent setting for auto-inserted blocks when processing templates with PHP on the server. Templates, template parts, and patterns get loaded from HTML files and processed separately, but we can always tell what the parent is even for the top-level blocks: no parent, core/template-part or core/pattern.

ancestor

The current definition in the handbook:

This one would be extremely difficult to support fully in PHP on the server because templates, template parts, and patterns get loaded from HTML files and processed separately. In fact, it made me realize that the same issue exists in the block editor when editing Template Part, Synced Pattern, or Post Content (including the post editor) blocks in isolation. The reason for that is that only in the Site Editor when editing the theme template you have the ability to scan the entire tree of blocks to correctly detect whether the conditions for ancestor can be fully satisfied.

supports.inserter

The current definition in the handbook:

My question is whether we should hide the toggle that brings back a removed auto-inserted block in the sidebar when inserter is set to false. Related to that, should the same toggle be exposed in the UI when template locking is applied to the parent block?

supports.multiple

It's something that also @nerrad explored recently with #53925.

The current definition in the handbook:

The wording is most likely a bit outdated, as it should work the same way with templates. If it would apply only to editing posts/pages/other CPT then we could ignore it because they are always crafted by the user, so there shouldn't be any case where block gets auto-inserted. Regardless, I believe that supports.multiple works in the site editor, too. It has a similar caveat as ancestor in the case when users edit parts of the template in the zoomed-in mode. In addition to that, it's really up to the theme author to ensure that static files shipped respect the supports.multiple flag when all of them get combined together to deliver the site to the user.

---

My current take on supporting the intersection between auto-inserting and the existing Block APIs shared above is that we should skip it for the time being. Instead, we should document what to expect and leave it all to the devs to share feedback whether it is essential to add native support to any of the behavior listed above. We might still want to tweak the UI in the editor's sidebar to account for certain rules that you normally see in the inserter.

[gziolo]

I'm concluding that at this stage, this project is all about setting proper expectations and communicating them with a very high attention to detail. It’s crucial to emphasize that the auto-inserting blocks feature works only with static templates loaded from HTML files shipped with the theme, maybe with plugins, too. The logic will never apply to the content provided by the user or templates (and partial templates) modified by the user.

Sorry if it's a silly question, but would it be possible to create a rule for the post content blocks where a certain pattern is inserted e.g. after a certain amount of paragraphs or every x amount of paragraphs? Could be a cool plugin-less way to manage ads with synced patterns, or to add a table of contents block as part of a template but within the post content.

I think that question is perfectly valid and only confirms what I said above. The way the feature is currently implemented, it won't insert any block inside the post content because it's crafted by the user and sourced from the database. In my testing, I noticed that firstChild and lastChild aren't compatible with the Post Content block, too. However, this particular block works with before and after insertion points when the block is embedded in the theme's template. The same limitation for firstChild and lastChild applies to Synced Pattern (formerly known as Reusable Block core/block). I would expect the same applies to the Pattern block (core/pattern), although the interesting part is that because it might load the content from an HTML file, so in that case it still could contain auto-inserted blocks inside.

It's also important to note that some blocks can have a very complex rendering logic. The Navigation block (core/navigation) would be one of the examples. In that case, while it's still possible to user firstChild and lastChild, there is no guarantee that these blocks will get auto-inserted because the block itself might in very specific situations skip using the child blocks provided and use its own alternative logic to render blocks. It's an edge case, but I thought I will mention it to make the point again that we need to set proper expectations.

[nerrad]

My current take on supporting the intersection between auto-inserting and the existing Block APIs shared above is that we should skip it for the time being. Instead, we should document what to expect and leave it all to the devs to share feedback whether it is essential to add native support to any of the behavior listed above. We might still want to tweak the UI in the editor's sidebar to account for certain rules that you normally see in the inserter.

I would agree given the complexities involved. Are there still plans to experiment with a low-level filter to expose the option for devs to exert finer control over the behaviour of the API for certain blocks (apologies if this has already been addressed somewhere)?

[ockham]

I would agree given the complexities involved. Are there still plans to experiment with a low-level filter to expose the option for devs to exert finer control over the behaviour of the API for certain blocks (apologies if this has already been addressed somewhere)?

Yeah, I'm planning on getting something like that into 6.4. My current plan is to do that on top of the code once it's ported to Core, see #53987 (comment).

I'm kicking off the porting today, so hopefully I'll have a filter ready some time next week.

[gziolo]

I opened #54293, which explores what's necessary to stabilize the Block Hooks feature. I also included some preliminary versions of the minimal additions to the documentation.

We will most likely have to provide a feature detection based on some new function introduced in WordPress 6.4. This will ensure that the custom logic added for the feature runs only for older versions of WordPress. For WordPress 6.4 and above, it should be all natively supported with the changes outlined in https://core.trac.wordpress.org/ticket/59313 and proposed in WordPress/wordpress-develop#5158.

[gziolo]

While testing the removal of the experimental feature guard in #54293, I did some additional testing for lesser-explored parts of the Block Hooks integration. In particular, @ockham raised that we might be injecting the hooked block to every Block Pattern integrated with the inserter, no matter if it comes from the file on the server shipped with the theme, Block Pattern Directory, or the regular register_block_pattern call that every plugin can use. The good news is that the integration between Block Hooks and Patterns was very solid in my testing, and I couldn't find any surprising issues:

The intriguing detail is that it seems like Block Hooks integrates with all sorts of Patterns even in the Inserter:

The remaining question would be whether we want to limit it only to the case when it's loaded from the file on the server. For the record, I was testing with the Like Button plugin. I modified block.json with the following using the planned stable API:

---

Everything also works as expected for the core/pattern block that sourced the pattern from the theme's patterns folder. Example for Twenty Twenty-Three and Call To Action Pattern:

---

In the case of Pattern created in the editor (stored in the database), they aren't connected with Block Hooks:

The only remaining edge case would be to check what happens if such a pattern when connected through core/pattern in the template or template part would get blocks hooked. I don't know if that is even possible because these patterns get stored as core/block.

[gziolo]

Make sure the panel doesn't show up outside of Site Editor (?)

I can confirm that the panel shows up in the Post Editor when it isn't expected:

[gziolo]

I filed an issue with a very subtle bug that applies on the frontend of the website for hooked blocks that use firstChild or lastChild positioning:

• Block Hooks: Incorrect placement in the parent container for hooked blocks #54307

[nerrad]

I can confirm that the panel shows up in the Post Editor when it isn't expected:

For this use case you pointed out @gziolo, why wouldn't we want it to show up? Its unclear to me why we'd wan the auto-insert behaviour to be restricted to the site editor context only...

[colorful-tones]

Wow 🤯 I just did a deep dive and caught up on all this amazing work. 👏 This has the potential to empower extenders to do some neat things.

The only case where we care about storing the intention is when a user wants to toggle off / remove an auto-inserted block, since we need to explicitly mark that on the container.

As previously expressed by @mtias

I do wonder if there is a possibility of designating a mixed state. I hate to introduce further scope creep, but I could not help but think of something like a 'Reset' link that shows up if the auto-inserted block has been moved from the original $property_mappings designated by the plugin. However, I'm likely missing some larger pieces to that puzzle. 🤔

My handy design work 🙃 to try and express this in the new UI 👇

Either way, I want to get playing with this and test and will try to report back. Thanks for this amazing contribution! 🙇

[gziolo]

I can confirm that the panel shows up in the Post Editor when it isn't expected:

For this use case you pointed out @gziolo, why wouldn't we want it to show up? Its unclear to me why we'd wan the auto-insert behaviour to be restricted to the site editor context only...

Good question. I must admit I didn't think about that too much. I have documented my findings based on the todo item added before:

Make sure the panel doesn't show up outside of Site Editor (?)

I don't have strong opinions here. I know that there is a call for testing planned, so I believe keeping the current state would be the best way to move forward. We can always update the Post Editor experience later if that really gets raised as a concern.

[gziolo]

Incorrect placement in the parent container for hooked blocks when using fistChild or lastChild (#54307) is fixed with #54349. There is still an edge case that we need to discuss further. The handling for the case with no inner blocks but the existing HTML wrapper for inner blocks isn't handled perfectly. A good example is the Columns block with 3 columns, where one of them is empty:

<!-- wp:columns -->
<div class="wp-block-columns"><!-- wp:column -->
<div class="wp-block-column"><!-- wp:paragraph -->
<p>First</p>
<!-- /wp:paragraph --></div>
<!-- /wp:column -->

<!-- wp:column -->
<div class="wp-block-column"></div>
<!-- /wp:column -->

<!-- wp:column -->
<div class="wp-block-column"><!-- wp:paragraph -->
<p>Third</p>
<!-- /wp:paragraph --></div>
<!-- /wp:column --></div>
<!-- /wp:columns -->

In such case, the hooked block set as firstChild for core/column block would still get injected, but outside the div wrapping element:

<!-- wp:column -->
<!-- wp:my-plugin/block /-->
<div class="wp-block-column"></div>
<!-- /wp:column -->

So the question is whether we should prevent injecting the hooked block if there are no other inner blocks, or should we seek ways to inject it in the correct place. The latter can be quite difficult to handle as the inner HTML for the block sometimes is more complex, example for the Cover block:

<!-- wp:cover {"url":"http://localhost:8888/wp-content/uploads/2023/09/Maldives.jpg","id":18,"dimRatio":50,"layout":{"type":"constrained"}} -->
<div class="wp-block-cover"><span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span><img class="wp-block-cover__image-background wp-image-18" alt="" src="http://localhost:8888/wp-content/uploads/2023/09/Maldives.jpg" data-object-fit="cover"/><div class="wp-block-cover__inner-container"></div></div>
<!-- /wp:cover -->

<div class="wp-block-cover__inner-container"></div> is the wrapper for inner blocks.

[Ren2049]

Would a text interface like "2 parent 3 child 2 grandchild" work that's based on the block structure inside the post/page editor? Where the user would count the parent and child blocks in the list view where he wants to have the hook injected, and then sets the parent and child numbers within the interface of the hook.

Or maybe it's even possible to display a popup that looks like a simplified mini list view limited to parent, child and grandchild block levels.

Would it be possible to let the user specify the location and then trigger an automatic insertion into that location?

[ockham]

Update:

Last week, @gziolo stabilized the feature (by removing its __experimental status), and fixed a bug that had lead to incorrect positioning for blocks hooked in the first child or last child position.

That aside, the main focus has been on porting the code to Core; there's a dedicated Trac ticket for that. We managed to file PRs and commit them for the first four items on the list, which were smaller changes that we could land fairly independently to lay the foundations. Building on those foundations, this week's focus will be on implementing actual hooked block insertion.

[gziolo]

I started PR with the changes to Gutenberg plugin:

• Plugin: Ensure that Block Hooks work correctly after landing in WP core #54651

[fabiankaegy]

I can confirm that the panel shows up in the Post Editor when it isn't expected:

For this use case you pointed out @gziolo, why wouldn't we want it to show up? Its unclear to me why we'd wan the auto-insert behaviour to be restricted to the site editor context only...

I just chatted with @gziolo a bit about this and I have another usecase where I think it would be nice to show the UI for inserting blocks in the post editor.

I'm working a lot on client builds and one of the struggles we are running into is clients struggling with deeply nested block structures. And when you for example build a card in the query loop which intern used a bunch of rows and stacks to accomplish a design you are trying to create the nested structures get quite complex.

It would be nice to leverage the UI for the "Block Hooks" in all editors to more easily allow users to toggle on / off a feature.

This should not auto inject anything into the post content of a user without them doing something. Instead it should only render the toggles and inject the block when the user enabled the toggle.

Whats nice about this instead of having them manually insert the element is that an excerpt block for example is self aware enough to know that likely the best place for it is right after the post title. So this greatly simplifies the experience. And also makes it much easier to remove blocks if you won't want them enabled.

So we would essentially use the defined "insertion" rules from the auto inserting bocks but only run that logic when the user enables the element on the parent block :)

[annezazu]

Marking this as blessed for major release per this slack discussion.

[ockham]

Update:

With WordPress/wordpress-develop#5261 landed, Block Hooks are now functional in Core trunk and on track for 6.4 🎉

There's still a bit of follow-up work that I'd like to get in before Feature Freeze; I've updated the issue description to reflect that 😊

[ockham]

I'll file a new, post-6.4 tracking issue for the remaining items on the list, and will close this one.

[ockham]

I'll file a new, post-6.4 tracking issue for the remaining items on the list, and will close this one.

#54904.