contentOnly patterns: mark patterns as contentOnly by adding metadata.patternName to the root block #73477

ramonjd · 2025-11-21T06:05:15Z

Tip

This PR is largish, but intentionally so. It handles the migration from template hooks (which was buggy) and ensures the feature works only when the content experiment is activated.

What?

This PR:

refactors contentOnly patterns: mark patterns as contentOnly by adding metadata.patternName to the root block #72988, which used hooks to parse patterns in templates, to extend the template controllers taking into account the template activate experiment.
ensures that template activation is taken into account

These changes ensure that patterns returned in registered theme templates and template parts have pattern metadata, so that themes that use patterns automatically opt into the content only behaviour.

In Core this is done in WP_REST_Registered_Templates_Controller

Why?

Extending the class is required as parsing and re-serializing blocks disrupts the render chain, in particular it breaks shortcodes in patterns and also render_block_core/pattern hooks.

See:

Thanks to @dd32 for helping debug.

How?

When the active_templates experiment is enabled, WordPress uses a different REST controller (Gutenberg_REST_Registered_Templates_Controller) to fetch theme templates.

Registered theme patterns are returned from the /wp/v2/registered-templates endpoint.

Tests have been added to cover both scenarios (with the experiment on and off).

Testing Instructions

Check out this PR and head over to /wp-admin/admin.php?page=gutenberg-experiments to enable the contentOnly: Make patterns contentOnly by default upon insertion experiment.

I'm using TT4 to test.

Head over to /wp-admin/site-editor.php?p=%2Ftemplate

In the browser network console, you can check the response of /wp/v2/registered-templates to see if the template content contains pattern metadata (search for metadata)

Now edit the All Archives template (or any that contains a pattern).

In the list view, check that the post 3 col pattern is in content only mode, that is, that it only displays text and other blocks (not containers and so on)

Now enable the template activation experiment and test again.

Check that patterns still work by running through the test steps in #73375

Ensure that with the content only experiment OFF you cannot reproduce these test results.

Screenshots or screencast

Before	After

…o extend the template controllers taking into account the template activate experiment. This is required as parsing and re-serializing blocks disrupts the render chain, in particular it breaks shortcodes in patterns and also render_block_core/pattern hooks, because the wrapping pattern was not there.

…for 'gutenberg-content-only-pattern-insertion'. This change modifies the `prepare_item_for_response` method in both the block patterns and templates controllers to conditionally resolve pattern blocks based on the experiment's status. Additionally, updates to the test cases ensure the experiment is enabled during tests, improving performance and reliability.

github-actions · 2025-11-21T06:05:24Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ramonjd <[email protected]>
Co-authored-by: andrewserong <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

lib/compat/wordpress-7.0/template-activate.php

lib/compat/wordpress-7.0/class-gutenberg-rest-block-patterns-controller-7-0.php

lib/compat/wordpress-7.0/rest-api.php

lib/load.php

ramonjd · 2025-11-21T06:09:35Z

phpunit/class-resolve-patterns-in-template-parts-test.php

@@ -0,0 +1,355 @@
+<?php


Test overkill? Maybe.

But given the experiment ping pong and the class juggling with template activation, best to be safe.

…nsistently resolve pattern blocks using `gutenberg_resolve_pattern_blocks`. Removed conditional checks for the 'gutenberg-content-only-pattern-insertion' experiment in the `prepare_item_for_response` methods. Updated related test cases to remove experiment assertions, enhancing test clarity and performance.

github-actions · 2025-11-23T08:25:37Z

Flaky tests detected in 51279fa.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/19723850485
📝 Reported issues:

[Flaky Test] should show the original content after revert, clicking undo then redo in the header toolbar #47896 in /test/e2e/specs/site-editor/template-revert.spec.js

lib/compat/wordpress-7.0/class-gutenberg-rest-templates-controller-7-0.php

…ller-7-0.php Co-authored-by: Andrew Serong <[email protected]>

andrewserong

Looking pretty good so far! I haven't tested manually yet, but I noticed an issue in the rebase where the class-gutenberg-rest-static-templates-controller.php file still exists instead of being renamed. I've left a comment about whether we should retain that name for now, or include the renaming in this PR.

I like the inclusion of the tests, as you mention, while they're a little verbose, good to include some coverage given all the back-and-forth!

lib/compat/wordpress-7.0/class-gutenberg-rest-templates-controller-7-0.php

phpunit/class-resolve-patterns-in-template-parts-test.php

lib/compat/wordpress-7.0/template-activate.php

- Replaced the `Gutenberg_REST_Registered_Templates_Controller` with `Gutenberg_REST_Static_Templates_Controller` in the load file. - Deleted the `class-gutenberg-rest-registered-templates-controller.php` file. - Updated the `class-gutenberg-rest-static-templates-controller.php` to extend the correct base class. - Made minor adjustments in the `class-gutenberg-rest-templates-controller-7-0.php` for clarity in the code comments. - Adjusted the template activation process to reflect the new controller structure.

… 7.0 - Added a note indicating that there are no changes in this class that need to be backported to core. - Minor formatting adjustment in the code for improved readability.

- Added registration for the Registered Templates Parts REST API routes. - Updated the `gutenberg_modify_wp_template_post_type_args_7_0` function to simplify its parameters. - Introduced a new function `gutenberg_modify_wp_template_part_post_type_args_7_0` for handling template part registration. - Updated PHPUnit tests to verify pattern resolution in template parts via the REST API.

andrewserong

Thanks for all the back and forth on this one, this looks good to go to me! Smoke tested to ensure that the contentOnly experiment is still working nicely with patterns contained in template parts (i.e. footer in TT4), and included in templates (e.g. archive in TT4). Toggling the experiment on and off is working as expected.

LGTM! 🚀

ramonjd · 2025-11-27T05:49:43Z

Thank you for helping get this one across the line @andrewserong

Hopefully we won't break wordpress.org 😄 (I tested this against the https://github.com/WordPress/wporg-parent-2021/tree/trunk branch and it looks okay)

ramonjd added 2 commits November 21, 2025 16:24

ramonjd requested a review from spacedmonkey as a code owner November 21, 2025 06:05

changelog

db0aee8

ramonjd self-assigned this Nov 21, 2025

ramonjd added [Type] Bug An existing feature does not function as intended Backwards Compatibility Issues or PRs that impact backwards compatability [Feature] Patterns A collection of blocks that can be synced (previously reusable blocks) or unsynced labels Nov 21, 2025