Template Hierarchy
The Hybrid Core template hierarchy feature gives you a smarter, more logical hierarchy for your templates than the WordPress defaults. You are, of course, free to use the regular WordPress template hierarchy. Hybrid Core just offers you something different as a developer.
If you do decide to use this feature, you must follow the guidelines below when building your templates. You don’t have to use every template, but you must use at least the fallback template.
If you’re a theme user rather than theme developer, you can use following guidelines as a reference.
Enabling the template hierarchy feature
If you’re already using a theme from here, don’t worry about doing this step. Your theme should already support this feature out of the box.
To enable the template hierarchy feature in a custom theme you’re building off Hybrid Core, you need to add the following code to your theme setup function.
add_theme_support( 'hybrid-core-template-hierarchy' );
Visual overview of the template hierarchy
After enabling the feature, your templates will have a hierarchy as shown in the following image.
The hierarchy
The framework basically takes the default WordPress template hierarchy, extends it, and shuffles a few things around to make it more organized. There are several major types of templates. Everything falls back to index.php
.
Blog template
When WordPress was first created, it was simply a blogging platform. Therefore, the “home” page needed to only show posts. Since that time, WordPress has grown into a more powerful CMS, allowing anything to be on the home page. Unfortunately, the name “home” has stuck, even when we’re not viewing the home page.
The theme keeps this legacy template (home.php
) to handle the posts page. In the future, this will likely be changed to blog.php
. Because of naming conflicts with a different template, we’re sticking with home.php
for now.
Technically, home.php
is the file used when on the posts page (or the blog page). If this is confusing to you, check out the tutorial on the difference between “home” and “front page”.
Blog hierarchy
home.php
index.php
Singular template
Singular templates are the templates used to show an individual post (page, attachment, etc.). By default, WordPress gives you a ton of flexibility with pages but hardly any with other post types. The theme recognizes the need for custom templates in all sorts of situations.
Singular hierarchy
{$post_type}-{$custom}.php
{$post_type}-{$slug}.php
{$post_type}-{$id}.php
{$post_type}.php
single-{$post_type}.php
(added in 1.3)single.php
(added in 1.3)singular.php
index.php
While most post types will work like this, attachments are a bit different. Those templates use the attachment mime type. For example, you might have an image attachment with the mime type of image / jpg
($mime[0] / $mime[1]
).
Singular attachment hierarchy
attachment-$custom.php
attachment-{$mime[0]}_{$mime[1]}.php
attachment-{$mime[1]}.php
attachment-{$mime[0]}.php
attachment.php
single-{$post_type}.php
(added in 1.3)single.php
(added in 1.3)singular.php
index.php
Taxonomy archive templates
Taxonomies are a way to label your posts or possibly other objects. By default, WordPress provides the category, post tag, post format, nav menu, and link category taxonomies. But, you can also create your own taxonomies. The hierarchy for these taxonomies is:
Taxonomy archive hierarchy
taxonomy-{$tax->name}-{$term->slug}.php
taxonomy-{$tax->name}.php
taxonomy.php
archive.php
index.php
Post type archive template
When creating custom post types that have an index/archive, you can create a custom archive template to display these pages. It works just like any other archive. Essentially, it’s the equivalent to the blog/home (posts page) except its for a specific custom post type.
Post type archive hierarchy
archive-{$post_type}.php
archive.php
index.php
User/Author templates
WordPress generally calls this file the author.php
file. It is typically used to display the post archives of a writer for your site. However, WordPress also creates this page for all users, including those without permission to edit or publish posts. Hybrid Core calls this the “user” template.
User/Author hierarchy
user-{$user_nicename}.php
user-role-{$role}.php
user.php
archive.php
index.php
Date-/Time-based templates
Generally, the date.php
file handles all instances of these types of archives. Hybrid Core takes this one step farther and breaks these down into the specific type of time archive shown.
Date/Time hierarchy
minute.php
hour.php
time.php
day.php
week.php
month.php
year.php
date.php
archive.php
index.php
Search template
There’s nothing new here. Hybrid Core uses the default WordPress search.php
file to display search results.
Search hierarchy
search.php
index.php
Error template
WordPress relies on the 404.php
file when a user visits an invalid URL.
404 hierarchy:
404.php
index.php