A recent search of the theme directory turned up one theme that looked as if it uses custom template part areas.
One theme.
Whether developers aren’t finding uses for these handy tools or they just don’t know about them yet, template part areas are so useful that you probably are already using them in your block themes. (You just didn’t realize it …).
After this tutorial, maybe you’ll be psyched enough to experiment with custom template part areas in your themes.
But first, let’s look at how they work and how to register your own, so you’ll know exactly what you’re psyched about.
What are template part areas?
Again, if you’ve built a block theme, you have likely used them. And, again, maybe you didn’t even know it.
Template part areas define an area of the page as a place where one of a specific set of template parts can live. For example, a Header area is meant for site headers. You can even stick the—you guessed it—Header template part in the Header area.
Confused yet? Why does WordPress have a Header area when there’s a Header template part already?
Think of it as a taxonomy of sorts. Your theme may very well have two, three, or even a dozen different headers that you want the user to choose from. Perhaps a dozen is overkill, but YOLO—you do your thing and have fun with it.
The great thing about this system is that your users can pick and choose the template part that they think works best in a given area.
WordPress defines three default areas:
headerfooteruncategorized(titled General in the UI)
You can use these areas when you register a custom template part in theme.json. Just make sure you define the area value, as you see below. By the way, these are of course the two most common template parts registered in block themes: Header and Footer:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"templateParts": [
{
"area": "header",
"name": "header",
"title": "Header"
},
{
"area": "footer",
"name": "footer",
"title": "Footer"
}
]
}Technically, you could name the Header and Footer template parts anything you want. Most theme authors use those names purely by convention. But to distinguish them from other headers, you might consider going with Site Header and Site Footer.
Notice, below, that in the Site Editor, you can see the Header and Footer areas under the Template panel:
One important role that this panel has is to help you navigate from area to area. If you click on the Header area, it will jump you to the Header in the template.
That might not seem like much when a template has only two parts. But when you’ve registered multiple custom areas in a more complex template, you’ll be glad you have some easy ways to get around that morass.
Plus, template part areas let you switch among all the template parts or block patterns you’ve registered for that area.
To give this a test, select the Header area and then click the ⋮ (Options) button in the toolbar. Now click the Replace Header option in the dropdown menu. That action will bring up a modal with the available template parts or patterns for that area:
From there, you can replace your existing Header with one you like better.
Before getting your hopes too high, this replacement feature is not currently supported for custom template part areas. Sorry. There is an open ticket to make that magic happen, but it never hurts to develop for the future. For now, you can only replace the Header and Footer.
Registering template part areas
Now for the fun part! It’s time to build your own template part areas.
A couple of common areas in theme templates are the sidebar and comments sections. Without custom areas, you would need to register them as uncategorized. The UI labels these as General, and if you have multiple uncategorized template parts on a page, you just as quickly have bought yourself a UX nightmare.
Let’s try improving this experience with a custom Sidebar template part area. After you register it, it will show up in the Site Editor like this:
Here’s how you do it. First, add a filter to the default_wp_template_part_areas hook. Your callback function should accept a single parameter named $areas, which is an array of area definitions.
Add this code to your theme’s functions.php file, and you will have registered your first Sidebar area:
add_filter( 'default_wp_template_part_areas', 'themeslug_template_part_areas' );
function themeslug_template_part_areas( array $areas ) {
$areas[] = array(
'area' => 'sidebar',
'area_tag' => 'section',
'label' => __( 'Sidebar', 'themeslug' ),
'description' => __( 'Custom description', 'themslug' ),
'icon' => 'sidebar'
);
return $areas;
}Only four icons are supported for the icon argument. header, footer, sidebar, are the named icons; all other values revert to symbolFilledIcon. There is an open ticket to address this limitation, but it lacks the patch that would move it forward. This might be a “good first ticket” for someone to get involved with Gutenberg development.
Now, registering an area will not automatically make it appear in the Site Editor. You also need to register at least one template part, and that template part must also be inside the template you are currently editing.
Adding template parts to custom areas
With your custom Sidebar area registered, you can start assigning template parts to it.
Start by adding a sidebar.html file to your theme’s /parts folder. You can put whatever valid block markup you want in it.
Then, call that template part from anywhere in a top-level template, like /templates/single.html, or /templates/home.html, with this code:
<!-- wp:template-part {"slug":"sidebar"} /-->Now, register the part for the area. Open your theme.json file and add your template part for the sidebar area:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"templateParts": [
{
"area": "header",
"name": "header",
"title": "Header"
},
{
"area": "sidebar",
"name": "sidebar",
"title": "Sidebar"
},
{
"area": "footer",
"name": "footer",
"title": "Footer"
}
]
}Next, visit the Site Editor and make sure everything works: your sidebar should show up in any templates you’ve called it in, and the Sidebar area should appear in the Template panel.
Want more? Try registering a few more sidebar parts—maybe a couple for the homepage and your site’s shop:
//...
{
"area": "sidebar",
"name": "sidebar-home",
"title": "Sidebar: Home"
{
"area": "sidebar",
"name": "sidebar-shop",
"title": "Sidebar: Shop"
}
//...Be sure to add sidebar-home.html and sidebar-shop.html files to the /parts folder in your theme and call them in their respective top-level templates.
So now you know the secret sauce of blissful block-theme UI: template part areas. You’re in a prime position to keep expanding on these basics, to build all kinds of template part areas for your themes.
Which ones will you add first?
Props to @marybaum, @bph, and @ndiego for feedback and review.
Leave a Reply