Block API: Stabilize Block Hooks feature #54293
Conversation
gziolo
force-pushed
the
update/stable-block-hooks
branch
from
c6b3f13
to
276b481
Compare
|
This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress. If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged. If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack. Thank you! ❤️ View changed files❔ lib/compat/wordpress-6.3/rest-api.php ❔ lib/compat/wordpress-6.4/rest-api.php ❔ lib/experimental/editor-settings.php ❔ lib/experimental/rest-api.php ❔ lib/experiments-page.php ❔ lib/load.php ❔ lib/compat/wordpress-6.4/block-hooks.php ❔ lib/compat/wordpress-6.4/class-gutenberg-rest-block-patterns-controller.php |
gziolo
added
[Feature] Block API
gziolo
force-pushed
the
update/stable-block-hooks
branch
from
d26027b
to
ccd3c99
Compare
|
Size Change: -16 B (0%) Total Size: 1.52 MB
ℹ️ View Unchanged
|
| $gutenberg_experiments = get_option( 'gutenberg-experiments' ); | ||
| if ( $gutenberg_experiments && ! empty( $gutenberg_experiments['gutenberg-block-hooks'] ) ) { | ||
| // This can be removed when the minimum supported WordPress is >= 6.4. | ||
| if ( defined( 'IS_GUTENBERG_PLUGIN' ) && IS_GUTENBERG_PLUGIN ) { |
There was a problem hiding this comment.
It's very likely that we will have to refactor this code once the final solution is fleshed out in WordPress/wordpress-develop#5158.
|
There is a failing unit test: 
I'm investigating. |
gziolo
force-pushed
the
update/stable-block-hooks
branch
from
ccd3c99
to
87a2b29
Compare
|
The issue with the failing unit test was fixed with 87a2b29. |
| @@ -497,6 +497,23 @@ _Note: In JavaScript you can provide a function for the `isActive` property, and | |||
|
|
|||
| See the [the variations documentation](/docs/reference-guides/block-api/block-variations.md) for more details. | |||
|
|
|||
| ### Block Hooks | |||
There was a problem hiding this comment.
@gziolo I love these docs :)
The only thing that I'm confused about is that the docs as written here make it sound like the filters can be used for any blocks answhere. Which is not correct if I understand things correctly. Hooks only get applied for blocks inside non modified block templates of a block based theme 🤔
Is that so or do these hooks also fire for any block just anywhere saved in post content?
There was a problem hiding this comment.
Great catch. We definitely need to cover it, as communication is critical here. It only applies to block patterns (not generated by the user), template parts, and templates loaded from the block theme files. Essentially, the feature never changes the content created/modified by the user on the website, which I think is very intuitive once you wrap your head around how it all works. The only challenge I encountered myself is that it's difficult to tell where to clear modifications to see the blocks automatically hooked. Sometimes it's the template you work within the site editor, but sometimes it might be the template part. We can further improve the UI to make it more evident in the future.
By the way, I believe that we will also need a How-to Guide covering it all, a lengthy dev note, and a detailed blog post at https://developer.wordpress.org/news/ 😅 .
There was a problem hiding this comment.
By the way, I believe that we will also need a How-to Guide covering it all, a lengthy dev note, and a detailed blog post at https://developer.wordpress.org/news/ 😅 .
It looks like @ndiego already has it on his radar for the Developer Blog 🎉 WordPress/developer-blog-content#168
There was a problem hiding this comment.
I added a section to the block registration document with 7c0c3a0. I'm happy to apply some edits, but we should plan extending that part in a follow-up PR so we have time to stabilize the API before the next Gutenberg plugin release.
It’s crucial to emphasize that the Block Hooks feature is designed to work only with static templates, template parts, and patterns loaded from HTML files shipped with the theme. It also integrates with patterns registered on the server by the site. The modification will never apply to the post content or patterns crafted by the user, nor theme templates and template parts modified by the user.
There was a problem hiding this comment.
For now, this Trac ticket has some information on the feature and the architectural decisions (and tradeoffs) that went into it 😄
gziolo
force-pushed
the
update/stable-block-hooks
branch
from
87a2b29
to
7c0c3a0
Compare
gziolo
requested review from
TimothyBJacobs,
spacedmonkey,
ellatrix,
ajitbohra,
ryanwelcher and
juanmaguitar
as code owners
| } | ||
| ``` | ||
|
|
||
| It’s crucial to emphasize that the Block Hooks feature is designed to work only with static templates, template parts, and patterns loaded from HTML files shipped with the theme. It also integrates with patterns registered on the server by the site. The modification will never apply to the post content or patterns crafted by the user, nor theme templates and template parts modified by the user. |
There was a problem hiding this comment.
Surfacing the comment from @fabiankaegy added on the commit:
There was a problem hiding this comment.
👍 We could consider adding a note on why we're making that tradeoff (of not auto-inserting into templates with user modifications) (as explained here) -- but maybe that's too technical for this more hand-on kind of API documentation.
There was a problem hiding this comment.
@colorful-tones plans to open a follow-up PR that will include further improvements to the docs as outlined in 7c0c3a0#r127154283. Let's discuss that part alongside these changes.
|
Flaky tests detected in 7c0c3a0e815a0853af7db71e0745e057f8e882dc. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/6157833104
|
|
Already needs rebasing 🙀 |
Co-authored-by: Bernie Reiter <96308+ockham@users.noreply.github.com>
…ock Hooks feature Props to @fabiankaegy, @ndiego and @colorful-tones for helping with that part.
Props to @ockham for proposing edits.
gziolo
force-pushed
the
update/stable-block-hooks
branch
from
0112c23
to
02fd527
Compare
|
@gziolo @ndiego @ockham, the 'Like Button example plugin' (linked in the PR description above) requires the Gutenberg plugin to be enabled. However, this feature is part of the targeted WP 6.4 release. If I ran WP 6.4 Beta 3, dropped the example plugin, and activated it, it would work. However, it utilizes the Interactivity API, which seems to require Gutenberg. So, I'm wondering if:
Here is the beginning of the long stack trace for the Fatal Error thrown in WP 6.4 Beta 3 without the Gutenberg plugin enabled: |
|
The most recent version of the Like Button doesn't use the Interactivity API anymore. When the plugin was created, the expectation was that To be cristal clear, |
|
@annezazu, it might be worthwhile to mention and link directly to the Like Button plugin version that @gziolo linked (above) in Dev Notes and Source of Truth. The idea is that we do not want to make developers interested in testing or using the Block Hooks feature the quickest route possible to having a prototype to see in action; and not have to read through Issue(s) or PR(s) to get experimenting. |
Yes, I recalled reading and grasping that early on when attempting to follow along with the progress.
Yes, I was fortunate enough to know this from my prior knowledge when trying to follow along with the progress. However, I feared that other developers might not have the time to read through this entire Issue and come to the same conclusion. Thanks for clarifying @gziolo ! 👍 |
|
Sure thing! I'll add it to the source of truth as an example. |
What?
Adds all what's necessary to stabilize the Block Hooks feature. I also included some minimal additions to the documentation that should help later to shape the dev note.
Why?
To ship Block Hooks as a stable feature in WordPress 6.4 beta 1.
How?
Updates all code occurrences where the experimental name
__experimentalBlockHookswas used. It also removes the experiment that guarded the feature in the Gutenberg plugin.I believe that we still will have to provide a feature detection as a follow-up based on some new function that is going to be introduced for WordPress 6.4. This will allow ensuring 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.
Testing Instructions