Continuing with my full tutorial on building a WordPress theme from scratch, I will be talking about three very important files: home.php, front-page.php, and index.php. I am combining these three into one tutorial because based on decisions you make will determine which of these files will be your “landing page”. Think of it in terms of regular, static html sites. We typically put everything inside of the index.html file and your browser knows that this is the file to look for. In WordPress it is a little different because it is based on specificity. HUH!?! Yeah I just through that word in there to see if you were paying attention. What I mean, in plain English, is that the more specific you are with your naming of files the better WordPress knows what you are telling it to do with that particular file. None of this is going to make sense until I show you a few of the important options WordPress needs to know before starting development. Let’s dig in a little deeper.
This is the second article in the Let’s Build A WordPress Theme From Scratch Series.
If you go into your WordPress dashboard and find the settings tab, you will see a sub tab called Reading. Choose Reading and you will find a few very important choices to be made about your site. Before you choose any options, think about how your website has been designed. Is the “home page” going to be a lengthy, static page with various bits of information or will it be simply displaying blog articles? Maybe it is even both! Depending on how you answered that question will determine what we choose on the Reading option’s page. If your website is mainly going to be a blog then you would leave it on the default option of ‘Front page displays : Your latest posts’. The home.php file is the file that WordPress looks for FIRST when you choose this option. Therefore, the code that goes into home.php will be your “home page” code that displays your most recent blog posts.
LET’S TAKE A MOMENT: Do not confuse home.php for being the “home page” file template. WordPress is very intuitive for many different things but they didn’t exactly choose the best names for these files. The file home.php is only the “home page” file if you have chosen the option of ‘Your latest posts’ on the Reading option’s page.
Let’s say the website you are building is for a local business and they want a slider, followed by three main services they provide, followed by a block of text telling some “About the Company” info with a sidebar that would allow widgets to be displayed. In this case you would go into the Reading option’s page and choose ‘Front page displays : A static page’. You must then assign a page you have already created under the Pages menu tab, followed by what page should show your blog posts. If you don’t plan to have a blog at all, you can leave that second option blank. Now that you have chosen a static page, WordPress will automatically look for a file called front-page.php. All of the code to display each of the areas we hypothesized above will go inside of the front-page.php file.
Ok, now what is the index.php file for?? WordPress uses the index.php file for what they call the default fallback template. This basically means that if WordPress can’t find home.php or front-page.php it will then look for index.php as it’s fallback. So my recommendation, and what I personally do, is whichever option I have chosen to be my “home page” I will take the code from that file and copy and paste it into my index.php file. So if, for whatever reason, something happens to my main page’s file it will have a backup to keep your site running.
The last thing I would like to cover before we start digging around in the code is that NO MATTER WHAT, the template file you will use to code the page that will display your most recent blog posts will always be home.php. So if you have set up your static page to be your main landing page and then chose to have your blog posts appear on a page called blog, that page template will be home.php. Therefore, you are using both front-page.php and home.php in the same project but front-page.php has the code to show your main landing page content and your home.php file has the code to display your blog posts. We will see these files in action and be able to play with the code below. Let’s open them up and see what all of this means!
<?php get_header(); ?> <div class="wrap_1280"> <div class="main-content"> <?php get_sidebar(); ?> <div class="left-page-content col-lg-10 col-md-10 col-sm-9 col-xs-12"> <div class="container"> <div class="row" id="ms-container"> <?php if (have_posts()) : while (have_posts()) : the_post(); ?> <div class="ms-item row col-lg-6 col-md-6 col-sm-6 col-xs-12"> <div class="blog-page-content"> <?php if (has_post_thumbnail()) : ?> <figure class="article-preview-image"> <a href="<?php the_permalink(); ?>"><?php the_post_thumbnail(); ?></a> </figure> <?php else : ?> <?php endif; ?> <h2><a href="<?php the_permalink(); ?>" class="category-title-link"><?php the_title(); ?></a></h2> <div class="category-post"> <h6 class="article-meta-extra"> <?php if (has_category() && !has_category('Uncategorized')) : ?> <?php the_category(' | '); ?> | <?php else : ?> <?php endif; ?> Posted on <?php the_date(get_option('date_format')); ?> at <?php the_time(get_option('time_format')); ?> by <?php the_author_posts_link(); ?> </h6> <?php the_excerpt(); ?> </div><!-- END CATEGORY POST --> <?php if (has_tag()) : ?> <p class="tags"><?php the_tags('', ' '); ?></p> <?php else : ?> <?php endif; ?> <a href="<?php the_permalink(); ?>" class="btn btn-blue btn-block">Read More</a> </div><!-- END EACH BLOG--> </div> <?php endwhile; ?> <?php else : ?> <article class="no-posts"> <h1>No posts were found.</h1> </article> <?php endif; ?> </div> </div> <div class="clearfix"></div> <div class="article-nav clearfix"> <p class="article-nav-next pull-right"><?php previous_posts_link(__('Newer Posts »')); ?></p> <p class="article-nav-prev pull-left"><?php next_posts_link(__('« Older Posts')); ?></p> </div> <div class="clearfix"></div> </div> <div class="clearfix"></div> </div><!-- END MAIN-CONTENT --> </div><!-- END wrap_1280 --> <?php get_footer(); ?>
Let’s break this code down and show you the important functions and techniques we are using here:
- The first WordPress function we come across in the code above is the get_sidebar. No big surprise here, it gets the sidebar! In your functions.php file you can register and assign as many sidebars as you want. We will discuss this later in the series and go into detail about the template files you will use with sidebars.
- Next we will learn about The Loop which is basically the function that pulls in all of the content that you write in your posts and pages dynamically. The basic Loop structure looks like the one we have in the code above, but it can be expanded and used to pass in certain specifications about what type of data you want to pull in and how it will display. We won’t be going into this in major detail in this series but I will be writing a few posts about the Loop later on.
- The loop is written like this: if you have posts – it checks to see if you even have posts, then is says while you do have posts – show the posts! In php we have if statements that basically say — if something — do this — else do this. So if you follow the indentions of the lines in my code, you will see how everything lines up together. An if statement begins with an if, then gives you an else statment(not always required), and then ends in an endif. A while statement starts with while and ends with an endwhile. In the case of the Loop, you will see that we start with an if statement, then a while statement, then we end the while with the endwhile, then comes the else statement, and finally the endif to stop everything.
- In between the while statement and the endwhile statement we want to include the html to structure the layout of the blog posts. In the else statement it is always best to provide a simple sentence that says something like “Sorry! There were no posts found”. This is best practice just in case you haven’t blogged yet and someone goes to the blog page. This is more of a user experience thing but it is very important to know and implement.
- Inside the loop are a few really important functions, the first being the call for the featured image of a post. This function is called the_post_thumbnail(). I always start my call for the featured image by checking if one even exists. Again this is good practice. So we create another if statement that uses the function has_post_thumbnail(). So we are asking WordPress, is there a featured image? If so display it like this, otherwise, don’t show it at all. This may seem silly because if you don’t have a featured image it wouldn’t show up. This is more helpful in a case where you need things to be structured differently in the html if there is or isn’t a featured image. Again, this is more advanced stuff that won’t be included in this series but I will write about it at some point.
- You will remember from my first article in this series, we used the_title function in the header.php file. In this case, it will be calling in the title of the blog post.
- Let’s talk about the permalink! The permalink is your best friend! In the above code you will see that it is attached to the featured image and the title and is placed in the anchor tags src. This is because the_permalink() dynamically produces the link into the main post. Remember that we are looking at a list of blog posts that don’t show all of text and has a read more button. So by attaching the permalink to the src of our anchor tags, WordPress is doing all the work for you to link to the blog page that contains all of the content of that one single post. You won’t have to remember and write out individual paths like we would have to do on a static html site. Thanks you WordPress!
- To display the categories that are attached to each blog post, we use a function called the_category(). You can pass a parameter within the brackets that tell WordPress how to dynamically separate each category. In my code I use a space | space for separation. You will also see, much like the verification that there was a featured image, I use an if statement to see if there are categories attached. I also do a little trick where I say and ‘&&’ doesn’t have posts with the category of Uncategorized which is a standard and non-removable category in WordPress. This will make sure that it doesn’t show ‘Uncategorized’ in the category listing. It does not, however, prevent posts with ‘Uncategorized’ to show up. That is something else entirely! This is done with the function has_category()
- In the same fashion as the categories, the tags are written very similarly. They use the function the_tags() and the verification in the if statement uses has_tag().
- Let’s look under the h6 with the class of article-meta-extra and we will see three functions that aren’t always necessary but they are good to know. The first is the_date() function that brings in the date the blog post was originally posted. We pass the get_option() function as a parameter in order to grab the date format you have chosen to use under your dashboard settings. That makes things super easy and less work on your part. Next we have the_time() function that works the same way but calls in the time the post was posted. It then passes the get_option() function to pull in the time format you have chosen in your dashboard settings. And lastly, you have the_author_posts_link() function that provides you with the name of the person who wrote the article (if you have them set up as a user and they have filled out their profile) and a link to their individual author page.
- Man we have covered a lot of stuff already! The last two functions I want to show you are important ones! The first is the_excerpt() which calls the first few lines of the text from your post as a teaser to interest someone into clicking into it and reading the full article. The second is the_content() which I’m not using in the code above but goes hand in hand with the_excerpt(). The_content() calls the full article and would be used in the single.php file which is the template file to show the full post article.
This template file, because it would probably be a landing page, would only contain the needed html structure to accomplish the design you already have. So there isn’t really any specific code that I need to show you because it would be whatever you need to build your page. You can include the loop here, you can use WP_Query to call in custom loops if need be, or you can just have it be all static html. The one thing I will stress the importance of is including the get_header() and get_footer() functions at the top and bottom of this and every page.
<?php get_header(); ?> <!--ALL OF YOUR HTML FOR THE STATIC LANDING PAGE WOULD GO IN BETWEEN HERE--> <?php get_footer(); ?>
Last, but certainly not least is our backup/fallback file. Remember to keep this file updated with the most recent code from whichever page you have as your main page on your website. If you examine the template hierarchy in either the codex or the article I wrote, you will notice that index.php is basically the very last file WordPress looks for when it can’t find anything else. That is literally for all major files in our root folder. So you can see that it is a no brainer that if it can’t find the template file it needs, it is best that it takes you back to the main page. We will also talk later in the series about the 404.php page in case the page they are looking for doesn’t exist or your site has a bad link or two.
We definitely covered a lot today! What you need to get out of this tutorial is that WordPress isn’t as scary as you might have originally thought. Building a WordPress theme from scratch doesn’t have to be just a dream of yours. It can be a “right now” reality! You can see that there is minimal php going on. Most of everything is html creating the structure and css styling it. You just have to get accustomed to thinking about your knowledge of static html and then know how to cut it up and which file to place it into. The template file naming system WordPress has in place is actually very intuitive and once you get more into it you will see how much power they have given you. Keep practicing on your own and I will keep writing articles to help you on your journey.
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.