WordPress Custom Page Templates (or How I Solved the Issue of the Mystery Content)

closeThis post was published 5 years 4 months 20 days ago, which is pretty much forever ago in internet time. As such, some of what's discussed here may no longer work as described.
TL;DR: FYI, YMMV

WordPress custom page templates are very easy to create; so easy, in fact, that it was recently causing problems with a website I administer.

I inherited this site about a year ago from another developer who… Actually, to call him a developer is to give him more credit than he deserves. As you may imagine, there have been a number of issue with the site over the past year. Some were obvious, but others, like this one, have been laying in silent wait.

This particular problem reared its ugly head when I created a new page and assigned it an infrequently used template. When I viewed the page, it surprised me to see not the content I had written, but a page recently created by another developer at the company. He and I were initially baffled by this. It took some deeper investigation to reveal that my predecessor hadn’t fully understood how WordPress custom page templates work, and that this problem was larger than it initially appeared.

WordPress Custom Page Templates: Template Drop-down

The page templates drop-down menu with a custom Contact Form template.

WordPress Custom Page Templates

To fully appreciate how much of a problem this was, I’ll take a moment to explain how to create WordPress custom page templates. Let’s say you create a page for a contact form, and you want its layout different from the default page type (also note that we’re talking about pages here, not posts).

Assuming you’ve built the template correctly (which I won’t cover here, because “correctly” depends entirely on what the page needs to do), you need to do two things before it will show up in the Template drop-down.

The first is to put the file in the right directory on your server. The directory where you need to put your template file is your theme’s home directory:

example.com/wordpress/wp-content/themes/your-theme/template.php

I strongly suggest a clear naming convention for your template files, which is something the site I was working on didn’t have. Trying to determine which files were templates and which were regular pages was a huge pain.

An example of what I would use is: tpl-filename.php

You don’t have to do this, however. You can use almost anything you want as the filename, as long as it ends with .php and isn’t one of WordPress’s reserved file names.

Code Magic

The other thing you need to do is include a specific piece of code at the beginning of the file.

/*
Template Name: Name of Template
*/

WordPress looks through all the PHP files in your theme’s home directory when building the page template drop-down. If it finds a comment block like the one above, it includes value indicated after Template Name: (in this case, Name of Template).

Mystery Solved

It was this little block of text (in fact, that one line that specified the template name) that was causing problems.

Once I discovered the issue, I thought it would be as simple as removing the comment at the beginning of the file. It’s never that simple, though, is it?

What I quickly learned was that when my predecessor created new pages, he included the comment block in many of them (even the ones that weren’t templates). Many files shared the same comment block, so when I removed it from one file, another non-template file would take its place. I ended up making edits to over 50 different files to remove the comment block and get the site working as it should.

Further Reading

For more information about WordPress custom page templates, check out the WordPress Codex entry on the topic.

Leave a reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>