Page.php - Build A WordPress Theme

Today on Let’s Build A WordPress Theme From Scratch, our tutorial will look at the template file page.php which controls what is displayed on each of your pages. As you know, in WordPress there are posts and there are pages. When we build a WordPress theme we need to think about them separately because there are php templates that hold the code for the blog/posts and others that hold the code for the pages. For pages there is actually only page.php but there are instances where you would use a variation of it. For example, what if you don’t want every single page on your website to be structured and styled the same way? WordPress has you covered! It has the most intuitive naming scheme on the planet, in my opinion, and it allows you to do very powerful things. As you will notice later in the course, this naming structure works for many other template files as well. Let’s dig into it!

This is the fourth article in the Let’s Build A WordPress Theme From Scratch Series.


I wish that I had something really profound to say about page.php but alas, I don’t. It is literally the file that you put the code to display the page structure. It includes the Loop to dynamically call in the content from the corresponding page. You will remember we discussed the_excerpt() and the_content() in my article Let’s Build A WordPress Theme From Scratch – Home.php, Front-page.php, and Index.php that the excerpt only gives you a limited preview of the text from the article, whereas, the content shows you all of the text. In page.php it would be very unlikely you would need to only display an excerpt because you can’t go any deeper in the file structure than page.php. It is the equivalent to the single.php page template we will discuss in another tutorial. Enough about that! Let’s look at the code.

<?php get_header(); ?>

<div class="page-content-title-wrapper">
    <div class="wrap_1280">
        <h2 class="page-content-title"><?php the_title(); ?></h2>
    <div class="clearfix"></div>
    </div><!-- END WRAP_1280 -->

<div class="wrap_1280">
    <div class="main-content">
        <div class="left-page-content col-lg-8 col-md-8 col-sm-8 col-xs-8">
            <div class="page-content">
                <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
                    <?php the_content(); ?> 

                <?php endwhile; ?>
                <?php else: ?>
                    <p>No content has been posted to this page.</p>
                <?php endif; ?>
            </div><!-- END PAGE-CONTENT -->
        </div><!-- END LEFT-PAGE-CONTENT -->
        <?php get_sidebar('page'); ?>

    </div><!-- END MAIN-CONTENT -->
</div><!-- END WRAP_1280 -->

<div class="clearfix"></div>

<?php get_footer(); ?>

I would like to point out a few things before we move on:

  • the_title() is using the same html structure we have used in prior articles.
  • The loop is in the same if/while format we have seen before. Remember to only use the_content() not the_excerpt().
  • Right before the loop you will see a div with a class of left-page-content col-lg-8 col-md-8 col-sm-8 col-xs-12. This references the Twitter Bootstrap responsive grid and basically tells this block of content to be 8 out of 12 columns wide. The other 4 columns will be found on a div with a class of col-lg-4 col-md-4 col-sm-4 col-xs-12 in a template file called sidebar.php. This is because I am breaking up my page structure with a main area of content and then a dynamic sidebar where you can add widgets or whatever you need.
  • The last thing I want to point out is the get_sidebar() function being used at the bottom of the code. This displays the default sidebar you have created in your functions.php file and called/requested in your sidebar.php file. We will have a full tutorial on sidebars and the functions.php template later in the series. Notice that there is a parameter passed in the get_sidebar() function of ‘page’. This would be calling for a sidebar that you designated to only show on your pages. You can create as many sidebars as you need and allow them to display only on blog posts, a different one for pages, and maybe even have one on the home page. Why am I rambling on about this? Well this is leading to the naming system I talked about at the beginning of this lesson. Your default sidebar would use the sidebar.php template file, which I usually use as my home page sidebar. But then what template file would I use for a second sidebar I only wanted to show up on the static pages? WordPress makes it easy as pie! We would simply name the file sidebar-page.php. The -page corresponds with the name of the parameter we passed in the get_sidebar() function. For all my visual learners out there, sidebar-page.php correlates with get_sidebar(‘page‘). The same would happen if we now wanted a different sidebar for our blog pages. We would use get_sidebar(‘blog’) to call the sidebar in all of our blog related files and then add the structure of the html into a template file called sidebar-blog.php. Make sense?

Template File Naming System

When I first learned about this naming system in WordPress it blew my mind people! If you think that part was cool, I haven’t shown you anything yet! Let’s go back to page.php. You have used the code above to structure and style all of your pages with this one template file. But now you want your “Contact Us” page to be structured completely different. For pages, we have two options in the naming system. We can either use the slug like page-slug.php or you can use the id of the page like page-id.php. What’s a slug you ask? Well it is a small, slimy snail without a shell of course! But in WordPress it refers to the permalink of the page. Take a look at the picture below to see what I mean.
The slug - Build A WordPress Theme
The word contact that is highlighted in yellow is your page’s slug and can be found when you go into a specific page from the All Pages menu to the left on your dashboard. So if we wanted to use the slug to make a page template for our “Contact Us” page we would go into that page and look for the slug. In this case, my “Contact” page has a slug of ‘contact’ so my page template name would be page-contact.php. BAM!

Now finding the id of a page is a little more difficult. Go to your left menu on your dashboard and click “Pages”. A list of all of your current pages will show up in the window and if you simply hover/mouse over the name of the page you in question, a small black box will appear at the bottom of your browser window with a bunch of path information. You want to look for the part that says post= and then write down the number that is in single quotes. Let’s say your page id was 56, then your template file name would be page-56.php. Reference the photo below if you can find it.
The Page ID - Build A WordPress Theme

The naming system is so helpful/powerful. It will definitely help you build a WordPress theme much quicker and allow for much more diversity on your site. You can read more about the naming system on the Page Tempates page in the Codex.

We Aren’t Done Just Yet!

There is one more concept we need to discuss in regards to the page.php template file. I keep using the term “template file” over and over in these articles. If you click on the Pages link on the left dashboard menu and go into any page you will notice to the lower right corner of the page there is a panel called Page Attributes. The first option is in regards to hierarchy, which asks do you want this page to be a stand alone page or do you want it to be a child of another corresponding page. The second option ‘Template’ is what we will discuss further. Right now, if you are looking at the page, the ‘Template’ option should be set on ‘default template’. This means that WordPress will look for page-slug.php or page-id.php first and if it doesn’t find one that corresponds to the page in question it will then look for the default page.php file. WordPress likes to give us as many options as it thinks we might need. Before they implemented the naming system, they had this ‘Template’ option which allowed you to add a small bit of code to the top of your custom page template, we will call ours page-full-width.php, and it would create an option under the ‘Template’ drop down for you to choose. Here is the code.


  Template Name: Full Width


Let’s examine the code:

  • Even though we named the page template file page-full-width.php there isn’t actually a page with a slug of full-width. By using this method we don’t need the page name and the slug to match. We will physically set the template under the ‘Template’ option of the page we are editing.
  • You will notice that this template name is commented out which means only WordPress will see it and know what to do with it. You can rename the ‘Full Width’ portion of the code to whatever works best in your situation. Then go back to the Edit Page screen, refresh the browser, and you should see ‘Full Width’ option under the template drop down menu. If you choose it and click update, WordPress will use the template file you have the above code in.

Page Attributes - Build A WordPress Theme

Wrapping Things Up

Some of this stuff can be really hard to explain and therefore, be very confusing to understand. Please never hesitate to shoot me an email using my Contact Form if you have any questions about any of this stuff. I know that this Build A WordPress Theme From Scratch series seems like small bits of information, but I really wanted it that way. Each of these concepts need to be broken down into small bites so that you can absorb each piece and know how to use them altogether in the end. I am certain that once the series is done, you will have a much better understanding of how to build a WordPress theme and you will have this resource to come back to at any time. I am always available to answer questions and of course, I will be writing many additional articles after this series ends to help further your growth.

Team Treehouse – Learn PHP for WordPress

If you are serious about learning to develop custom themes in WordPress, I highly recommend you join Team Treehouse. They have a full video course on everything WordPress development, including a course on specifically writing PHP for WordPress.