Add support for replacing "general" template parts

[inc2734]

Description

Define your own template part area. Then, create multiple template parts that belong to that area. Open the site editor and insert one of the template parts you created.

At this point, in WordPress 6.0, you will see "Replace" in the toolbar of that template part, but not in 6.1.

It does not appear even after activating the Gutenberg plugin.

Step-by-step reproduction instructions

Since it is necessary to define the template parts area and create the template parts file, TT2 is used as an example.

1. Add code to functions.php.

function tt2_default_wp_template_part_areas( $default_area_definitions ) {
	return array_merge(
		$default_area_definitions,
		array(
			array(
				'area'        => 'tt2/template-part/test',
				'label'       => 'Test template parts',
				'icon'        => 'layout',
				'description' => '',
				'area_tag'    => 'div',
			),
		)
	);
}
add_filter( 'default_wp_template_part_areas', 'tt2_default_wp_template_part_areas' );

2. Create template parts.

Open /parts. And create this files.

/parts/test-1.html

<!-- wp:paragraph -->
<p>Test 1</p>
<!-- /wp:paragraph -->

/parts/test-2.html

<!-- wp:paragraph -->
<p>Test 2</p>
<!-- /wp:paragraph -->

3. Add code to theme.json.

	"templateParts": [
		// omission,
		{
			"name": "test-1",
			"title": "Test 1",
			"area": "tt2/template-part/test"
		},
		{
			"name": "test-2",
			"title": "Test 2",
			"area": "tt2/template-part/test"
		}
	]

4. Add template part on the site editor.

In 6.0, "Replace" appears on the toolbar.

Not shown in 6.1.

Screenshots, screen recording, code snippet

No response

Environment info

• WordPress 6.1 beta3
• WordPress 6.0.2
• Gutenberg 14.2.0

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[talldan]

Thanks for reporting this. It seems like there was a decision made in #40787 to only make 'Replace' work for Header or Footer areas. The button was also moved from the toolbar to the options menu.

I guess this triggers a discussion about the change in #40787. I see the purpose of removing the 'Replace' button for 'General' template parts, but themes can register additional semantic areas to Header and Footer, so perhaps 'Replace' should still be available for those. Otherwise, I wonder what the purpose of allowing themes to add areas is.

cc @jameskoster @Mamaduka @carolinan

[inc2734]

Thanks for the infomation!

the purpose of removing the 'Replace' button for "General" template parts

I see. I understand.

Users can easily change the layout by replacing template parts. I believe that is probably why the header and footer replacements were left in place. However, the content area between the header and footer can no longer be easily changed in layout. Posts and pages can be easily changed with custom templates, but archive pages, search results, and 404 pages cannot.

I used to take advantage of the template parts replacement feature in my theme to easily replace layouts in all types of templates, but since 6.1 all of these no longer work.

https://github.com/inc2734/unitone

If possible, I would like to see template parts other than General be replaceable.

[Mamaduka]

We might consider re-enabling this in the future if the replace modal is searchable.

I see this note in the original PR. We introduced to search for this modal in #42459.

I think James is AFK this week, but removing or altering restrictions shouldn't be a problem.

[jameskoster]

If possible, I would like to see template parts other than General be replaceable

They are, the replace flow was simply moved to the ellipsis menu:

[Mamaduka]

@jameskoster, only template parts assigned to Header or Footer area are currently replaceable - #40787.

[jameskoster]

I was responding to this comment:

If possible, I would like to see template parts other than General be replaceable

It seems like @inc2734 thought that headers/footers weren't replaceable now?

[inc2734]

@jameskoster @Mamaduka

It seems like @inc2734 thought that headers/footers weren't replaceable now?

I do know that the header and footer are interchangeable! I have made an issue about replacing template parts related to areas that I have added my own in default_wp_template_part_areas.

[jameskoster]

Ah I see. Sorry I was a bit slow on the uptake there :)

That use case seems perfectly fair to me.

I suppose we should revise the logic. Instead of "only headers and footers can be replaced" it should be "any template part except general can be replaced".

[ianstewart]

I suppose we should revise the logic. Instead of "only headers and footers can be replaced" it should be "any template part except general can be replaced".

Plus one. Just noticed the removal of replacement for general template parts and would plus one offering a replacement menu item for them as well. There's a lot of cool utility in being able to swap template parts in and out. My initial user reaction was to be confused at the difference.

[webmandesign]

Hi everybody.

Usecase description

Building my first block theme I use several template parts with various alternative layouts for the same functionality/area. For example a posts list (query) with and without a sidebar. Or alternative posts list entry layouts.

I must have tested the template part block replacement on a header or footer, so I happily presumed it works for every template part. And that's why I created multiple template parts for same areas: so users can choose which one they prefer.

You can imagine my frustration when I was trying to figure out what I do wrong in the theme as I couldn't replace my "uncategorized" template parts in Site Editor during testing. Finally I found this thread which provided me the answer. Sort of.

Issue

I don't really understand the reasoning for removing "Replace" button/menu for Template Part block.

1. Why this change even happened? (I have read Only allow template part to be replaced if its a header or footer #40787 but it does not seem to provide me with an answer.)
2. What's the reason for having a Template Part block when it is not replaceable?
3. What makes Template Part block without replace functionality different from a pattern? (Except maybe that template parts are user editable.)

Proposed solution

Please re-enable the "Replace" functionality for Template Part block regardless the template area. Having any restrictions here creates confusion from user experience point of view, I think.

Also, it would be great to have a "Replace" toolbar button (always visible for Template Part block) instead of hiding it in the options menu so users can actually immediately see that a Template Part block provides them with a great flexibility of swapping the template parts (unlike it is with patterns).

Thanks for re-considering this!

[webmandesign]

@jameskoster @Mamaduka Is there any progress on this please? Will we be able to replace template parts in next WP version (6.3)?

[annezazu]

@webmandesign came across this issue and wanted to note it hasn't been completed for 6.3 but that I've added this to the UX & Polish board since it appears to be a straight forward dev task.

[webmandesign]

Thank you for the update, @annezazu

[bgardner]

Chiming in to say that I would love to see this functionality, based on this: #52859

[jameskoster]

Currently there are dedicated modals for each replace flow:

• Replacing a header shows only header template parts and patterns
• Replacing a footer shows only footer template parts and patterns

This implementation primarily caters to semantic replacement flows, IE replacing 'Header A' with 'Header B'.

We can expand on that by offering generic replacement options too, IE replacing 'Header A' with 'General Template Part Z'. This is the sort of flow I was hoping to facilitate via #39308 (comment) (which needs a design revisit).

In the short term, the replace flow could trigger a modal that includes all template parts, with the contextual category pre-selected. IE replacing a footer would invoke something like:

[annezazu]

Thanks for chiming in with a possible design. Going to move this to the design section of UX & Polish based on the added label!

[daviedR]

+1

Please consider re-enabling the Replace functionality on all template part areas (General and other custom areas), not just Header and Footer.

This Replace functionality makes more sense to users who don't like self-editing and prefer to choose among theme's or plugin's preset layouts.

Theme designers or plugin developers can add custom areas and create several template parts for that area. Some examples of custom areas that could be implemented:

• Posts Loop
• Sidebar
• Hero
• Mini Cart (like added by WooCommerce)
• etc.

With the Replace functionality, users can easily switch between the available layouts.

Please also consider moving back the Replace button into the toolbar (always visible).

[spstrap]

Do you still provide a "replace" option only for "header, footer" areas? Are there any updates on this issue?

[richtabor]

To align a bit more here, the "Replace" functionality has iterated as a "Design" panel in the Inspector (related #63497).

[richtabor]

Theme designers or plugin developers can add custom areas and create several template parts for that area. Some examples of custom areas that could be implemented

We're getting pretty close to the current "shuffle" functionality within patterns though, where you can swap between patterns in the same category. Areas = pattern categories.