WordPress Theme Development single.php

We’re going to go through more of the basic WordPress Templates that might be included in a full theme. But before we do it’s time to introduce the concept of the WordPress Template Hierarchy.

Knowing the WordPress Template Hierarchy is an important part of development in WordPress. WordPress works with PHP Template files. It does not serve static HTML files by default, and unless it can see a certain set of files in a theme it won’t necessarily serve the content you want.

The hierarchy is the system that WordPress uses to know which template to serve and when to do it. If WordPress does not see the template it needs to see, it falls back to the next template. If it does not see that template, it falls back to the next, until it finds the index.php template.

In a previous blog, I talked about the differences between the home.php and front-page templates. The WordPress Template Hierarchy is how WordPress determines the difference.

In this blog I’ll cover some of the nuances of the Hierarchy while covering the following templates:

• category.php –
• archive.php –
• author.php –
• search.php –
• 404.php

Category Template

The purpose of the Category Template is to be a hold-all Template where we can provide links to other Post Categories. You can generate a list of posts in the same way you’d do when making your blog home page.

The WordPress Loop ends when it iterates through the last post it can find, or when it can’t find any content. In either case, we have the perfect place to provide a list of Post Categories.

<div class="post_list">                                  

    <?php if ( have_posts() ) : ?>

    <?php while ( have_posts() ) : the_post(); ?>

        <!-- Content that loops goes here --->
        <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a> </li>

    <?php endwhile; else : ?>

        <!-- The loop ends at this point -->
        There are currently No posts for this category. Try the following Cats... 

    <?php endif; ?> 

</div>

WordPress provides a method that does just that: wp_list_categories();.

<!-- Provide the method -->
<?php wp_list_categories(); ?>

<!-- Returns HTML like this -->
<li class="categories">Categories

    <ul>
	      <li class="cat-item cat-item-6"><a href="">Category Name</a></li>
      	<li class="cat-item cat-item-5"><a href="">Category 2 Name</a></li>
        . . . 
    </ul>
</li>

As you can see the method returns one HTML list item that is a container for a whole new unordered list <ul> element. So there is a containing element provided. You can see that inside the list is a range of classes that can be selected with CSS to customise the styling. You’ll be able to select individual list items but using the .cat-item class will be easier to manage.

Some info on the_category();

That method lists all the Categories on the WordPress database. There’s another method that only lists Categories that are assigned to a given Post. That method is the_category();.

<?php echo the_category( " // "); ?>

It only works on certain templates like single.php, author.php, archive.php or sometimes in the sidebar.php but it seems it does not on category.php itself.

What we get returned is a set of adjacent anchor elements. So we will need to put the tag in a containing element for easier management and styling.

<div class="category-container">

    <!-- the_category(); links -->
    <a href="http://localhost/wordpress/subdomain_2024/category/pages/" rel="category tag">Pages</a> 
    <a href="http://localhost/wordpress/subdomain_2024/category/posts/" rel="category tag">Posts</a>
    <a href="http://localhost/wordpress/subdomain_2024/category/templates/" rel="category tag">Templates</a> 
    <a href="http://localhost/wordpress/subdomain_2024/category/widgets/" rel="category tag">Widgets</a>    
                 
</div>

In the hierarchy, category templates are organised under the “Archive” Template Type. It’s like knowing the CSS Cascade. The template file, category-[slug_name].php overrides category-[id].php, which overrides category.php. Without category.php, WordPress will look for archive.php and finally fall back on the index.php template.

Archive ------> category-slugname.php ----> category-[id].php -----> category.php ----> archive.php ----> index.php

The Hierarchy organises Author Templates in the same way where they are organised under the Archive Page Type and certain variable templates override the other.

Archive ------> author-nicename.php ----> author-[id].php ----> author.php ----> archive.php ----> index.php

Whether you’re looking at Yearly or Monthly records you can use either the date or archive template. date.php overrides the archive template and could be used to better organise your template files.

Archive ----> date.php ----> archive.php ----> index.php

Singular Page Type

In WordPress, single.php and singular.php are template files used to display single posts, but they serve slightly different purposes. Singular can be used for Page Types as well as posts allowing you to serve a uniform page design across all post types.

Further down the hierarchy is the attachment.php template. The attachment.php template in WordPress is used to display individual attachment pages.. that is to say, files that are included in the Media Library.

Singular Page ----> attachment.php ----> single.php ----> singular.php ----> index.php

Home pages

The hierarchy is a lot simpler on some templates. For example, the Blog Index page falls back to either the home.php template or the index.php template.

Blog Index Home ----> home.php ----> index.php

Search

It’s easy to work with Search in WordPress. You can either use a Search function in your Template files or use a Widget. Or both.

Add a Search Widget to your widget area or choose a widget area if you have more than one.

Dashboard ----> Appearance ----> Widgets ----> Search Widget

And just like that, search functionality is up and running out of the box with WordPress. But if we try to use it, all we get returned is the index.php template.

Search ----> search.php ----> index.php

So, let’s add search.php to the theme.

search.php 

You can copy the code over from home.php into this template. This will include pagination methods.

<!-- post list lass Copied from home.php ->

<div class="post_list">  
                                
    <h3><?php printf( __( 'Search Results for: %s' ), '<span id="search_result">"' . get_search_query() . '"</span>'); ?></h3>

    <?php if ( have_posts() ) : ?>

    <?php while ( have_posts() ) : the_post(); ?>

        <!-- Content that loops goes here --->
        <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a> </li>

    <?php endwhile; else : ?>

        <!-- The loop ends at this point -->
        <li>No Search Items returned</li>

        <?php get_search_form() ;?>

    <?php endif; ?> 

</div>
    

WordPress provides a simple method for adding a Search form.

get_search_form() 

You can test it right away. And you’ll see it has worked because the form uses a query string in the URL bar. e.g.

/subdomain_2024/?s=photo+viewer?s=photo

A useful place to add this would be the else block of the WordPress Loop.

<?php endwhile; else : ?>

    <!-- The loop ends at this point -->

    <li>No Search Items returned</li>

    <?php get_search_form() ;?>

<?php endif; ?> 

Now let’s examine what this gives us.

<form role="search" method="get" id="searchform" class="searchform" action="http://localhost/wordpress/subdomain_2024/">
    <div>
		    <label class="screen-reader-text" for="s">Search for:</label>
				<input type="text" value="horizon" name="s" id="s">
				<input type="submit" id="searchsubmit" value="Search">
		</div>
</form>

You can see a form container with an ID and a class. And inside is a <div> element.

There’s a number of things you can do with a Search Results page. But one thing I want to demonstrate quickly is how to use the printf() function to show the search term. Show the search term on the search results page. See how the format identifier is a placeholder for a string storing the text that the get_search_query() method captures.

I contained it in a Span element to make the search string stand out on the page.

<?php printf( __( 'Search Results for: %s' ), '<span id="search_result">"' . get_search_query() . '"</span>'); ?></h3>

404

WordPress provides a 404 template. This is an important part of a WordPress theme. If for any reason a page or post can’t be found, it’s a chance to get the user back to the homepage or try to find the page they’re looking for again.

If you haven’t already, add 404.php to your theme and copy the code from page.php to it.

404.php

This is where the template stands in the Hierarchy.

404 Page Type - 404.php ----- index.php

In my example, I’ve added a class of .error_404_content which is a container element of the main content of the 404 page.

Any content could go here. You could put a link to the homepage in this element. You could put in a list of post categories or Archive links. But for my example, I’ve also added another search form as the gateway out of the 404 template.

<aside class="error_404_content">

    <h3>Error 404</p>

    <h4><?php get_search_form(); ?></h4>

</aside>

Summary of the Template Hierarchy

I’ll conclude this blog by providing a link to the WordPress Template Hierarchy. In the next blog, I’ll talk about Template Parts in WordPress themes and Custom Page Templates.