How to Create a WordPress Page Template

Creating a page template in WordPress is actually quite simple. This guide assumes you understand the basics of creating a Theme in WordPress and have your directory structure set up. We will cover how to create a page template, what directories the page template can be in, and the use of get_template_part() to simplify your files.

Creating a Page Template

Let’s say you want to create a basic page template to show up when you create a Page in the WordPress backend. You can name your template pretty much whatever you wish. Maybe we want an about page for our site? OK, let’s create a file in /wp-content/theme/my-theme/ called template-about.php.

<?php 
/* 
 * Template Name: About Page 
 */ 
?>

This is all of the code you need to tell WordPress that this is a page template. Go ahead and save the file and create a new Page in the admin area. You should see the ‘About Page’ exists in the template dropdown.

What Directory Should Page Templates Be In?

What a great question! As a developer, you know having a clean directory structure is the first step in having a maintainable codebase. There is one very important rule when it comes to page templates and directories and that is:

Page templates can exist in the Theme directory or one level deep.

Did you catch that? Hmm, just in case:

Page templates can exist in the Theme directory or one level deep.

Here at HostingAdvice.com, our directory structure tends to be something like this:

/wp-content    /themes       /my-theme          /templates-pages             template-about.php          /template-parts             /about                /about-intro.php                /about-content.php                /about-outro.php 

As you can see, the template-about.php page is one level deep in the Theme directory. This will allow WordPress to recognize the file (and template) exists and will also allow us to keep things straight.

There is also a /template-parts directory you may be wondering about. Well, we will talk about that in the next section, which you will definitely want to read.

Using get_template_part() to Keep Your Files Clean

The function get_template_part() lets us bring in PHP or HTML or whatever from another PHP file. You can read about the function in detail here.

So let’s build template-about.php in a little more detail to demonstrate how this works.

<?php  /*   * Template Name: About Page   */  ?>   <?php get_header(); ?> <?php get_template_part( 'template-parts/about/about-intro' ); ?> <?php get_template_part( 'template-parts/about/about-content' ); ?> <?php get_template_part( 'template-parts/about/about-outro' ); ?>  <?php get_footer(); ?>

A couple of items to note here are:

1. get_template_part() assumes the directories all the way up to the Theme directory, so you don’t need to include that and you don’t start with a /
2. get_template_part() assumes a .php extension, so you don’t (and can’t) call the file with a PHP extension. In the example above, you don’t pass the .php part of about-intro.php.

As you can see, though, this will keep our top-level template files clean and very readable. I would recommend using this method for virtually all of your template files.

As with most things, there is one gotcha, though, and that is get_template_part() uses files that have their own local scope, so setting a variable outside of the template-part and then calling get_template_part() won’t work.

For example:

This Won’t Work!

<?php /*  * Template Name: About Page  */ ?>  <?php get_header(); ?>  <?php get_template_part( 'template-parts/about/about-intro' ); ?> <?php $content = 'Hello there dear reader.'; ?> <?php get_template_part( 'template-parts/about/about-content' ); ?> <?php get_template_part( 'template-parts/about/about-outro' ); ?>  <?php get_footer(); ?>

If you try to read the $content variable inside of the about-content.php file, you will find this doesn’t work. Basically, you can consider template parts as self-contained PHP files.

But there is a way to work around this when you need to pass variables to and from template parts, and that is to use the include( locate_template() ) structure as follows:

This Will Work!

<?php  /*  * Template Name: About Page  */  ?>   <?php get_header(); ?>   <?php get_template_part( 'template-parts/about/about-intro' ); ?>  <?php $content = 'Hello there dear reader.'; ?>  <?php include( locate_template( 'template-parts/about/about-content.php' ) ); ?>  <?php get_template_part( 'template-parts/about/about-outro' ); ?>   <?php get_footer(); ?>

Something to notice here is when using the include( locate_template() ) structure, you need to include .php in your filename.

It’s a Wrap

That is pretty much everything you need to know about how to use page templates in WordPress. It is worthy to note that certain types of content have template names that are predefined. This is called the WordPress Template Hierarchy and is probably the next step of your journey into WordPress development.

As usual, feel free to ask us questions or leave a comment if we messed this all up!