WordPress Template Hierarchy
WordPress template hierarchy is the way WordPress determines what file in the theme will be used to generate the complete HTML for a given page of a WordPress website by following a strict file naming rules.
How WordPress determines which template files to use on individual pages? WordPress themes are made up of template files. These are PHP files that contain a mixture of HTML, Template Tags, and PHP code.
When you are building your theme, you will use template files to create different parts of your website. For example, you would use the
header.php template to create a header, or the
comments.php template to include comments.
When someone visits a page on your website, WordPress loads a template based on the request. The type of content that is displayed in by the template file is determined by the Post Type associated with the template file.
The Template Hierarchy describes which template file WordPress will load based on the type of request and whether the template exists in the theme. The server then parses the PHP in the template and returns HTML to the visitor.
The most critical template file is
index.php, which is the catch-all template if a more-specific template can not be found in the template hierarchy. Although a theme only needs a
index.php template, typically themes include numerous templates to display different content types and contexts.
WordPress searches down through the template hierarchy until it finds a matching template file. To determine which template file to use, WordPress:
- Matches every query string to a query type to decide which page is being requested (for example, a search page, a category page, etc);
- Selects the template in the order determined by the template hierarchy;
- Looks for template files with specific names in the current theme's directory and uses the first matching template file as specified by the hierarchy.
With the exception of the basic
index.php template file, you can choose whether you want to implement a particular template file or not.
If WordPress cannot find a template file with a matching name, it will skip to the next file in the hierarchy. If WordPress cannot find any matching template file, the theme's
index.php file will be used.
Template Hierarchy Example
To show template hierarchy in action we are going to create: - New category Hierarchy (hierarchy) - New post WordPress Hierarchy Example and assign it to hierarchy category - New files in our theme twentyseventeen: category-hierarchy.php category-33.php category.php
We will copy the entire content of
archive.php file and we will paste it in each of the new files.
At the top of each file we are going to put its file name within H2 tags
Also we have installed a plugin Show Current Template which shows what template file WordPress uses to display certain webpage. To use the plugin you must be logged while browsing the site and make sure the box in front of Show Toolbar when viewing site label on the Profile screen (to enter it click Users > Your Profile) is checked.
Here are our new files within the twentyseventeen theme folder:
To start our example on template hierarchy we are loading our site
http://hostpulse-demo.net and click on the category Hierarchy link
The first choice of WordPress to load a category archive is
category-hierarchy.php. Now let's rename this file to
_category-hierarchy.php and to refresh the same page:
Now WordPress uses the template file
category-33.php. But how we got this number 33?
Go back to Dashboard > Posts > Categories, hover over Hierarchy category and click Edit or Quick edit links:
Click within the address bar and you are going to notice
tag_ID=33 part of the URL. Following WordPress naming conventions we can create template files using
For example we can create template file
single-123.php and if there is post with
tag_ID=123 this file will be used by WordPress to display this particular post ignoring the existence of
To continue our example let's rename
_category-33.php and to load
The next file used by WordPress is
category.php. Let's rename it to
_category.php and to refresh the page in the browser:
This time WordPress used
archive.php template. Let's rename it to
_archive.php and refresh the page again:
WordPress uses the last available option
index.php. We cannot rename or delete
index.php file because WordPress will stop working:
If a visitor clicks on a link to a category page such as
http://hostpulse-demo.net/category/hierarchy/, WordPress looks for a template file in the current theme's directory that matches the request to generate the correct page.
More specifically, WordPress follows this procedure:
- First it looks for a template file in the current theme's directory that matches the category's slug.
- If the category slug is
hierarchy, then WordPress looks for a template file named
category-hierarchy.phpis missing and the category's ID is
33, WordPress looks for a template file named
category-33.phpis missing, WordPress will look for a generic category template file,
category.phpdoes not exist, WordPress will look for a generic archive template,
archive.phpis also missing, WordPress will fall back to the main theme template file,
Template hierarchy visual graphics
The following diagram shows which template files are called to generate a WordPress page based on the WordPress template hierarchy:
The same diagram is available online - by clicking on any link on the diagram you can find additional information from codex.wordpress.org.
Knowing how WordPress works and how to properly build the file structure of a WordPress site is one of the most important initial steps in creating WordPress themes.