Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs for block-based template parts in classic themes #446

Closed
justintadlock opened this issue Sep 14, 2022 · 7 comments
Closed

Docs for block-based template parts in classic themes #446

justintadlock opened this issue Sep 14, 2022 · 7 comments
Assignees
@justintadlock
Labels
6.1 Changes in 6.1 release themes Issues for Theme Developer Handbook

Comments

@justintadlock
Copy link

Issue Description

WordPress 6.1 is introducing block-based template part support for classic themes. This is an important step for gradual adoption of FSE. We need to update the "Gradual adoption" section of the "Converting a classic theme" page with info on how to make use of the feature.

URL of the Page with the Issue

https://developer.wordpress.org/themes/block-themes/converting-a-classic-theme-to-a-block-theme/

Section of Page with the issue

https://developer.wordpress.org/themes/block-themes/converting-a-classic-theme-to-a-block-theme/#gradually-adopting-the-full-site-editing
@justintadlock justintadlock added themes Issues for Theme Developer Handbook 6.1 Changes in 6.1 release labels Sep 14, 2022
@justintadlock justintadlock self-assigned this Sep 14, 2022
@github-actions
Copy link

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

@carolinan
Copy link
Collaborator

When this page is created, this section in the block editor handbook should be updated so that the content is not duplicated in two different handbooks:
https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-based-template-parts

@justintadlock
Copy link
Author

justintadlock commented Sep 23, 2022 •
edited
Loading

Requesting review and feedback for proposed section:

Adding block template parts in classic themes

Since WordPress 6.1, classic themes can add block-based template parts. The feature allows end-users to customize their output via Appearance > Template Parts in the WordPress admin. Theme authors must register support to enable the feature:

add_theme_support( 'block-template-parts' );

From that point, developers can add template parts to their theme's parts folder. For details on creating parts, see the template parts for block themes handbook page.

In general, a PHP-based template part that is included via get_template_part( $name ) can be replaced with a call to block_template_part( $name ). It only needs a corresponding parts/{$name}.html file and block markup. Headers, footers, and even sidebars can be turned into a block-ready area for users.

Important! Classic themes must add opening and closing <html> and <body> tags along with the appropriate wp_head(), wp_body_open(), and wp_footer() hook calls as usual. These are easy to overlook when replacing header and footer template parts.

@carolinan
Copy link
Collaborator

This text looks good to me.

@carolinan
Copy link
Collaborator

Should this concept be introduced on https://developer.wordpress.org/themes/basics/template-files/ or would that become overwhelming?

@justintadlock
Copy link
Author

This text looks good to me.

👍

Should this concept be introduced on https://developer.wordpress.org/themes/basics/template-files/ or would that become overwhelming?

After diving deeply into this subject for the past week, I'd say it depends. It's tougher to do this from an existing classic theme (often lots of fixes), but it's pretty easy to do from a new classic theme. It can definitely be a bit of mixed message too for someone new who doesn't understand the classic/block differences yet.

On a related note that I'm still mulling over, it might not hurt for us to have pages for different "workflows," depending on how a theme author wants to build a theme. Not sure what that would look like yet though.

@justintadlock
Copy link
Author

Added the block template parts section. Closing this ticket as complete since we reached that goal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@justintadlock justintadlock

Labels
6.1 Changes in 6.1 release themes Issues for Theme Developer Handbook
Projects
WP 6.1 Documentation
Status: Done
Milestone
No milestone
Development

No branches or pull requests
2 participants
@justintadlock @carolinan