The LOOP

The LOOP will take you through the structure of a WordPress template page. You will learn how you can modify a theme to customize the presentation of your content.

We will see how headers and footers are used to complete the body of the template page, and how the loop is used to process the WordPress query. We will also look at how the "template-parts" files draw the individual posts.

This project has the following steps:

  • Either set up a new WordPress site or work with the one that you set up in one of the earlier projects.
  • Be ready to use a couple of themes. We will look at different ways themes structure the HTML markup for templates. Have the current WordPress theme (Twenty Twenty-One) available, but also have Twenty Sixteen or Twenty Nineteen handy. Twenty Sixteen and Twenty Nineteen use one method for structuring the pages, while Twenty Twenty-One uses another. Start with Twenty Sixteen.
  • Create child themes for the themes and activate the child for Twenty Sixteen.
  • Examine the structure of the "Loop". The Loop processes the list of posts in the WordPress query, branching out to pull in the "template-parts" files for drawing the posts.

Project Set-up. You can continue working with any of the WordPress sites you set up previously, or you can start a new site. If you start a new site, I recommend naming it n413_loop. The instructions will assume you are using a new project. Set up a new database and do a fresh install of the Wordpress files, as explained in The INSTALL. Be sure to namespace the table names if you are adding this project to a database that already contains other projects.

OVERVIEW. Behind all the user-friendly interfaces WordPress employs to keep you from ever needing to deal with HTML, there is ordinary CSS and HTML markup being delivered to the browser. Most end users of WordPress will never see this, but anyone who needs to customize a theme has to understand what is happening behind the scenes.

The Template. The main body of the page is delivered by a "template" file. There are different types of templates for single posts, for lists of posts (categories, search results, etc.), and for other layouts, such as pages. (See The HIERARCHY for a fuller discussion of the template files, and how to know which files are used in which situations.) For the discussion here, assume archive.php is used for categories and similar lists of posts, while single.php is used for pages with single posts.

Headers, Footers and Sidebars. There are also templates for specific sections of a page, such as headers, footers, and sidebars. Look inside the theme directory to see the files for these parts. Each of these templates draws a section of the page markup, and each theme will distribute the markup into different template files, based on the features the theme supports, and the design strategy of the theme developer.

The header template will contain the <head> tag with the links to CSS and Javascript, the opening <body> tag, and any "nav-bar" markup for menus, etc. The footer template will contain the footer code and corresponding closing tags to finish the markup. The main template for a page that displays posts will contain "The Loop". This is PHP code that will process one or more posts contained in the WordPress query. More on this later. But almost always, there will be some sort of "container" structure in the markup that will enclose the posts and associated page content.

The THEMES. The three themes we are considering here (Twenty Twenty-One, Twenty Nineteen, and Twenty Sixteen) all use the following container structure to enclose the main content section of the templates: 

<div id="content" class="site-content">
    <div id="primary" class="content-area">
        <main id="main" class="site-main" role="main">
            .
            .
            .
        </div>  <!-- /#main -->
    </div>  <!-- /#primary -->
</div>  <!-- /#content -->
  • Banners and top-of-page content would be inserted between the #content and #primary elements.
  • Sidebars would be inserted as sibling elements to the #primary element, with left sidebars being placed before the #primary element, and right sidebars placed just after the close of the #primary element. CSS would be used to float the elements left or right, and adjust the widths. See The SIDEBAR for more information about working with sidebars.
  • Pagination and previous/next navigation for the posts would be placed inside the #main element along with the post content.

Where the themes differ is the placement of these elements in the template files. Twenty Nineteen and Twenty Sixteen will place the #content element in the header file, while the other two elements are found in the main template files, such as archive.php and single.php. Twenty Twenty-One places all three elements in header.php. Elements opened in header.php will be closed in footer.php. (Elements opened in the main template file will also be closed in the same file.)

The result of this placement is that with archive.php and single.php, structural changes (sidebars, page-top features, etc.) can be customized independently with themes that place the inner containers in their main template files. For themes that place the containers in the header and footer files, customization will effect all the templates (including page templates) that use the header and footer. Work-arounds for this would include customizing header and footer templates in the child theme, or calling "special" versions of the header or footer files from the get_header() and get_footer() functions in the template file.

Not all themes use this structure, and some use a similar structure, but different naming conventions, such as "wrapper" for the container elements. If you understand the pattern, you can examine the HTML markup to work out the structure being used.

The LOOP. Most main template files will have a comment placed at the start of the Loop. If you don't see the comment, look for a "while" loop that looks like this: 

while ( have_posts() )

This loop will iterate through the posts array in the WordPress query, passing each post to a "template-parts" file, which is a mini-template used for drawing the posts in various contexts.

First, some explanation about the WordPress query. When a WordPress URL is called, several things happen in the PHP scripts upstream of the main template file. The URL itself provides much of the information needed to fetch the required posts. Values can also be passed to WordPress in the URL query (the "GET" portion of the URL that follows a question mark). This information is used to create an SQL query for the database, and the result is a large PHP data structure (a combination of arrays and objects) that contain all the data for drawing the page.

One section of this data is the posts array. The first function call inside the Loop is "the_post()", which will pull a post object out of the array and make it available for processing. The post object will contain the post name (or "slug"), the post title, the post content, and other items, such as the date, the author, etc. Inside the Loop, this data is easily used, as there are special methods that can access the data in shorthand ways.

However, you will not see much of the code that actually draws the posts in the Loop itself. Instead, a "template-parts" file is called to render the post into HTML markup. In the theme directory, there will be a sub-directory called "template-parts" and it contains several PHP files with names like content.php, content-single.php, etc. In the Loop, you will see a function called get_template_part(), which will have two arguments. The first is the path to the "template-parts" directory (and may have sub-directories), along with the first part of the file name. The second argument contains the second part of the file name (if any). The two parts of the file name are joined by a dash and the ".php" extension is added to complete the file's path. This method allows logic to be used to compute the appropriate template name, depending on the post type, or other requirement.

Each theme handles this task a little differently and some are more complex than others. It is fairly easy to see with Twenty Sixteen. If you look at single.php, you will see where the loop calls the template-parts file: 

(twentysixteen/template-parts/single.php)
...
// Start the loop.
while ( have_posts() ) :
    the_post();

    // Include the single post content template.
    get_template_part( 'template-parts/content', 'single' );
...

This will fetch a file named template-parts/content-single.php. The content-single.php file is a little difficult to decipher, but you can easily see where the post is preceeded by an <article> tag, then there is a <header> tag, with a WordPress function to get the post title (the_title()), which uses <h1> markup as the argument for the function. Then there are theme-specific functions to get the "excerpt" (which is a passage from the post text) and the image. 

(twentysixteen/template-parts/content-single.php)
...
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
    <header class="entry-header">
        <?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>
    </header><!-- .entry-header -->

    <?php twentysixteen_excerpt(); ?>

    <?php twentysixteen_post_thumbnail(); ?>

    <div class="entry-content">
        <?php
            the_content();
...

Following this is markup to create a container for the post content, and a call to the_content(), which fetches the text body of the post.

The file goes on to set up links to other pages, etc., but you can see several opportunities to style and customize the way the posts are drawn to the page.

  • Place a template-parts directory in your child theme folder, then copy content-single.php into it.
  • Edit the <h1> tag in the the_title() function argument to change the size of the headline. You can add a style (either inline or in the style.css file) to change the headline color or other property.
  • Delete the call to the twentysixteen_excerpt() function and write your own version, using the standard WordPress function, the_excerpt().
  • Take a similar approach to the thumbnail function, styling the post image to your preference. The WordPress function the_post_thumbnail() will fetch the image, and you can find details about how to size the image here.
  • Style the text content with your own CSS styles for the "entry-content" class (or by inserting your own inline style tag).

Create child theme copies of your template files and try some of these changes. Keep in mind that changes to the styles.css code may require a browser refresh to see, so inline styles offer instant gratification. You will start to understand the power of the child theme to make fundamental changes to your WordPress look and feel.

This type of post display styling has even more impact for pages where lists of posts (archives) are drawn. The size and styling of the thumbnail, the amount of text drawn for "excerpts", and other details are all elements that create a distinct design statement for the pages.

Start digging around in the archive.php template and find which template-parts file is being used to draw the archives posts (hint: it's just content.php). What if you could make the images small and just draw the excerpt instead of the full post text? If you copy the file to the child theme, you can hack around without fear of breaking WordPress, so give it a try!