Theme Hybrid
Plugins & Themes

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.

Hybrid Core Template Hierarchy

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