Stop using “page-” as a prefix for your themes page template files

Much has been written already about the WordPress template hierarchy. It’s an important part of WordPress, and understanding it is of vital importance to build proper themes. There’s a Codex entry devoted to it, Wptuts+ has created a cheat sheet for it and many, many articles have been written about its basics.

But, as is the case with many other WordPress topics, an at first sight promising list of results for a search query on the subject turns out to be a list of articles and tutorials that pretty much contain exactly what’s already in the Codex, but in a more readable format. What should be a list of interesting topics about the WordPress template hierarchy, its roots and why it is as it is, is actually the same article over and over again.

There’s an upside to this: if you want to know what file name you should use for your 404-page, you can find it spelled out for you in at least twenty languages and in a great variety of forms. Awesome!

The downside to this is that there are actually very few articles related to best practices as far as file naming is concerned, and even fewer articles going somewhat in-depth on the template hierarchy. And even though the naming requirements are quite strict, it does leave much room for ambiguity and other problems.

Page template file naming regulations

One of these problems – to get back on topic – is that there is no naming regulation for page template files. You, as a user, are allowed to name your template files whatever you want. For example, you can call your template file snarfer.php, like the example in the Codex entry for Pages (remind me to change that), if you fancy doing so. Naming your theme template file like this has two disadvantages.

Firstly, the file name does not immediately show that we’re dealing with a template file here. We could be dealing with a template part or any other file a theme contributor decided to add for the theme.

The second disadvantage is bigger and is actually a problem in many existing themes: you can declare any file in the root of your theme folder a page template — including files that are part of the rest of the template hierarchy. You can even make a page template of archive.php or 404.php.

Ambiguity in file names

So what’s the effect of this? Well, for starters, it’s highly confusing. 404.php for example, which is intended specifically when there is no post or any other type of content found, can actually be used for a specific page – the exact opposite of the reason for its existence.

The origin of the problem

This problem becomes more visible because of the naming convention for pages, which originates from the pre-custom post types era. Where custom post types have template file names single-{post_type}.php for displaying posts of a specific post type, pages use page.php, where we may expect single-page.php as page is a post type. Keeping this part of the template hierarchy intact is — even though it might not reflect the underlying structure of WordPress — probably a good idea, as all current themes would break upon changing it.

The naming of Page Templates has lead people to believe that it is good practice to name their page templates page-{templatename}.php. Tons of themes — even popular themes and themes considered to be well-built by the WordPress community — use this naming conventions, developers being unaware that this can be very inconvenient for their users.

Now I’m not blaming all developers who do this for the issue: it has been common practice (not good, but common) for many years now, and it is even encouraged in some articles. I’ve also heard some people considering this a “handy featured”, rather than an issue.

Effects of the lack of proper file naming

The thing is, the page-{templatename}.php naming is already in use in the Template Hierarchy: it’s used by page-{slug}.php, where a page with slug “foo” would (if it had no template file, that is) check if there was a page-foo.php file when determining its proper template.


Putting this issue into context, I will explain the problem with a common Page Template used by themes: a page template for a contact form. In many, many cases this Page Template is in a file named page-contact.php. Now, as most websites have some sort of contact page, the theme user will most likely want to create such a page. But let’s say this user doesn’t want the default contact form, he wants to use Gravity Forms (like I do on this website, what a coinsedence) using a shortcode in his or her otherwise default page (i.e. no page template). Now, he can not give his page the slug you would expect: “contact”, as that will show the user the contact page supplied by the theme via the contact page template.

A simple workaround for this would be add a page template for your own contact page and assign that to the contact page, as that is above the page-{slug}.php file in the template hierarchy.

Though this will work, it does not address the bigger point here: WordPress needs regulation for the naming of Page Templates. Allowing everyone to use any name for their page templates that they consider appropriate is not only confusing, it can actually cause problems in development.

The solution

Declaring a file a page template should not be done by adding “Template Name” just like you shouldn’t be able to declare a file to be an archive by adding “Archive For” to the file. Following the WordPress naming conventions in the bigger part of the template hierarchy, I would suggest prefixing page template files with a string specific to page templates (followed by a hyphen, of course). What I use is tpl-{templatename}.php, which immediately makes clear that we’re dealing with a page template, and doesn’t leave much room for confusion.

In my opinion, it would be best to enforce this: files without the page template prefix should never be considered page template files, but it’s probably a bit late to enforce this as it would break of most themes. The least we should do, however, is make sure that this becomes the standard and the proliferation of page template naming choices and the inevitable issues resulting from that become problems of the past.

Sharing is caring!

20 thoughts on “Stop using “page-” as a prefix for your themes page template files

  1. YES! This is a huge pet peeve of mine, and I appreciate that you took the time to layout the many reason’s it’s such a bad idea.

    Now that <a href=""page templates can be stored in a subfolder of the theme, I think that’s another great way to help clarify what’s going on. My preference is to prefix the filenames AND do the subfolder so there’s no confusion.

    • Jesper says:

      Thanks for sharing your views. I’m personally not a fan of storing page templates — or any templates for that matter — in folders just for the purpose of grouping them based on the template type (e.g. header, sidebar, page template, etc.), besides template parts called via get_template_part. However, if you decide to group all your page templates in a subdirectory, I do think you shouldn’t also prefix them, that’s just overdoing it.

    • I’m with you, Mark. I’ve really enjoyed being able to put my page templates into another folder. I hate it when I get a theme or project that has a bajillion files in the root of the directory. I’m a big fan of folder structure and grouping things together into logical groups makes sense to me, and helps me to keep things organized.

      Jesper, I find it curious that you don’t like using subfolders to group your page templates together based on your thoughts here. I would think that, in order to better organize the files, you’d be in favor of grouping files into a logical folder structure?

      • Jesper says:

        Thanks for sharing your thoughts on this, Nathaniel. In response to you and all others who use the subfolder approach, I’ll briefly explain my reason for using a prefix rather than a subfolder.

        In my opinion, the WordPress theme folder structure is quite rigid in its design. All templates, be it for single pages, headers, footers, archive pages, comments sections and so forth are supposed to be — and can only be, if I’m correct — in the main theme folder. This enforces a hierarchy where everything that outputs HTML (except for template parts called via get_template_part) via native WordPress methods is housed in the main theme directory.

        Separating page templates from this hierarchy breaks this structure, as suddenly main templates are placed outside of the hierarchy level of the other main template files.

        In my opinion, page templates are templates for pages just like single.php and archive.php are, and therefore belong in the main plugin directory. As is the case with archives and single pages, they should be prefixed with a unique prefix only used for templates (such as tpl-) to adhere to the WordPress theme file structure.

    • Putting all page templates in a sub folder is my habit. It keeps the theme clean and I don’t need to think about prefix or suffix, just keep the semantic file name. I also recommend this to my clients.

  2. Love it. The benefit to using tpl-*.php for me is that it keeps the templates together in the file view. That’s huge when digging through code to make changes.

    • Jesper says:

      That’s another advantage indeed! However, if you’ve got so many files that you’re actually losing overview, it might be a good plan to get some more structure into your files by separating template parts that you’re calling via get_template_part and any other, non-template files from the main theme folder.

  3. Gabriel says:

    I agree 100%. I use a different naming convention other than “tpl”, but basically I do exactly as you recommend

    In the past, I’ve had some trouble naming the page templates, the same thing that you mention happened to me and I was never sure if the template was being activated by the slug or by selecting it on the page editor

    Regards from Argentina!

  4. Yup, good advice. I use template- instead of tpl- but that’s neither here nor there.

    If you need to see which template files are actually in use just look in the post_meta table of the database for the key _wp_page_template and you’ll see the name of the file being used. Here’s the SQL query…

    SELECT * FROM `wp_postmeta` WHERE `meta_key` = '_wp_page_template';

  5. Interesting, I hadn’t thought of this. I usually use the page-{slug} naming on client work because they don’t add templates themselves, but for a public theme I’ll be releasing I’ll definitely do this

    • Jesper says:

      That’s not actually the problem; it doesn’t matter whether your clients add templates themselves. One of the problems I described was when people add a page with the same slug as the second part of your page template file name, e.g. when the slug of their page is contact and you have a page template named page-contact.php. The person adding the page might nog want to use that template, but by choosing the slug contact he or she is forced to do so.

  6. Hussain says:

    Although, I am an experienced programmer, I am new to WordPress.

    This page- prefix really is confusing to a newbie. I inherited a WP site and just couldn’t figure out why different pages had different layouts even though while editing a page (in WP) showed that all of them were using the default template.

    This, in effect, means that you need to mess around with the file system simultaneously with the WP editing. Bad! Bad!

    With the page- prefixing method, one basically needs to go poke around all the file system folders and sub-folders to check which templates have been provided. Plus, name the pages with the same slug, And make copies of the php files where a similar slug is to be used. Just goes downhill from there.

  7. Yep, good point Jesper, it’s something that I’m trying to get out of the habit myself since noticing a similar issue with a plugin.

    I’m curious, if you have a php file inside a subfolder and you give it a template name, this get’s picked up by WordPress as a new template on the edit screens, so therefore, is there any reason we could not create a subdir called page templates? And split them off?

    I often find on large sites that the theme directory can get bloated with many templates. I think a sub directory would make for better organization but have been concerned this may mess around with the WP template hierarchy system?


  8. Why can’t they all just be put in sub-folders? I am coming from an Expression Engine point of view and building a custom WordPress theme. In EE you have a templates folder. All templates go in there, its clear as mud. I am doing this in WordPress, because it seems the organisation of WordPress files in a theme is bad! It seems templates, css, common files (header, footer) are all lumped together in the theme root. This is bad. Sub-folders would be much better to organise files. Here is my strucutre:

    In fact I am tempted to put assets into an assets folder which I think improved organisation even more:


    • I could not agree more with this. The main them folder gets bloated and ambiguous.

      All of this could be built in conditionally – so those that know can use the subfolders – or not. To keep it backwards compatible with older themes. And it could be recursive – you decide how deep you need to go. Obviously shallow is better – but in bigger websites – kaboom.

      But it just make sense to be able to build subfolders
      templates/index.php *default for posts
      templates/page.php *default for pages
      templates/post-type/single.php *default for single post profile

    • Generally a good idea, but for the sake of clarity, don’t use “page” as a term. A site is built of individual components, so a term like “templates” or “template-parts” (an analogy to get_template_part()) for a folder of these component parts makes sense for individual files.

      For custom templates which the editor can select in the backend, choose a non-reserved term. Using page-X.php will confuse the issue: consider that WordPress automatically recognizes some file names. For example, a request to /myspecialpage/ should automatically find a template called page-myspecialpage.php. “Page” is a reserved term, so use something like “template-X.php” instead.

Leave a Reply

Your email address will not be published. Required fields are marked *