WordPress Template Files

I want to highlight a neat feature of WordPress today called WordPress Template Files. This isn't anything new in the WordPress world, but I found it to be nifty, and the way it's done in the newest default WordPress theme (Twenty Twenty) is a little different from how it was done in the past.

Out of the box, the Twenty Twenty WordPress theme has a couple different default templates for page layouts. These are Default, Cover, and Full Width. Default has some fairly standard wide margins, Cover allows for a huge cover image to display a sort of parallax effect that sits behind the page title, and Full Width eliminates most of the margins for something closer to a full-bleed layout.

You can also apply, to a limited effect, some of these templates to specific pieces of content. So if you are using the Cover template, but you want one specific image to be full width, you can apply a full width layout to that image.

However, what happens if you want a new template, based off one of these default templates, but with specific styles that only show up on pages that use this new, custom template? This is exactly the situation I found myself in, and I'd like to walk through how I addressed this need using WordPress Template Files.

Live Stream Pages

The pandemic had put our large-scale productions on hold since March. However, in mid-September we started doing audience-less tapings for Austin City Limits, to try and continue producing new content for the show's 46th season. A band would perform in the studio, and production staff did their production and recording duties, all within strictly defined protocols in a closely regulated environment. Everyone was spaced out, and no one was in the building who was not absolutely essential for the production or performance efforts.

In an effort to continue to keep our sponsors and supportive audience members (the Friends of ACL) happy, we live streamed these recordings on an unlisted YouTube video. The web needs to support this were straightforward enough, but also very important. The website needed pages to wrap the embedded YouTube video, and that wrapper needed to recognize our corporate and membership support for the show (something that would under normal circumstances be available across the venue on monitors or in programs for the taping), as well as provide information about the artist and a link to purchase the poster for the evening's taping.

Therefore, my workflow was as follows:

1. I built and styled a template for these streaming pages in WordPress. I placed sponsor logos, titles, and other recognition where it needed to go, and filled in dummy content that would be swapped out for each taping.
2. On the day before the taping, one of the content editors would duplicate that page, then swap out the dummy content for the real content, which would be the YouTube video, show poster, and artist biography.

It seemed simple enough, but once I started building that page wrapper, I started to run into some style limitations with the WordPress theme that I was using. Some of the page padding in one area would be way too big. Or I couldn't do a full-bleed black colored background for just the section of the page that has the page title and streaming video. Hard-coding out the page wouldn't be an option, as we didn't want to have to have a web developer build a page for every single new taping, and none of the available WordPress templates did what I wanted. We needed something that content editors could easily reuse.

WordPress Template Files to the Rescue!

The solution was something called WordPress Template Files. Template files are PHP files that you can upload to your server that allow you to fine-tune the layout of pages that you designate to use that particular template. A developer customizes the page in code once, and then content editors can reuse that template going forward.

To start, I created a file called template-stream.php, which I placed in the templates directory within my child theme. In my case, this directory also contained the files template-cover.php and template-full-width.php, which correspond to some of the default templates that WordPress Twenty Twenty comes with (mentioned earlier).

In order for my custom template to appear as an option in the WordPress backend, I needed to add a little bit of information to the top of your template file:

<?php/*Template Name: Stream TemplateTemplate Post Type: post, page */get_template_part( 'singular' );

The commented-out frontmatter in this code block is super important. It tells WordPress the name of the template, and what post types are permitted to use this template. the get_template_part() function tells the server which template part to use for the rest of the page.

With just this little bit of PHP in the file, the template shows up as a layout option within the Page Attributes section of the WordPress editor:

This now opens up a lot of formatting options. Say you want a page element, for example <h2>Live Stream</h2> to appear on the page. You can use something like the following:

if ( is_page_template( 'templates/template-stream.php' ) ) {  // the following shows up for Stream Template pages  <h2>Live Stream</h2>} else {  // this will show up for any other templates  <h2>Not a Live Stream</h2>}

Another cool thing about this custom template is that it adds a class name to the page body that is unique to this new template. In this Stream Template example, the class that is added is page-template-template-stream. As such you can do some template-specific CSS:

body.page-template-template-stream > main#site-content > article {  padding: 0;  background-color: #000;}

The above CSS is a simplified style rule that eliminates some of the padding that I didn't want for this specific template, and gives the article element a black background color.

So in creating this one WordPress Template File, I'm able to do some styling and page content formatting that only gets put into play when that specific template is selected. Otherwise, the Twenty Twenty default styles will be used. Pretty sweet!

This blog post only scratches the surface of WordPress Template Files. For a really great deep dive into the topic, you should check out A Detailed Guide To A Custom WordPress Page Templates by Nich Schäferhoff in Smashing Magazine.