WordPress Theme Development single.php

In this Blog Post, I’ll talk about Template Parts in WordPress themes, Custom Page Templates and in a more general sense, organising your theme files.

Organising custom templates.

I’ve already talked about how Custom Templates can allow you to create a custom design, if for example you need something unique for content in the Page Post Type. Now I’m going to discuss the “how to” and pitfalls in organise your template files into component parts and better organise custom templates into your themes.

In my example, I have a few Custom Page Template files; each in the root directory.

• page-template_archive.php
• page-template_author.php
• page-template_category.php
• page-template_search.php

Let’s try to organise them into directories of their own.

I use DOS/Bash a command line interface to manage files such as to create directories on my Windows system but you can use whatever GUI your operating system uses, as well.

mkdir pages

I have a page-template_archive.php fileon this website for which I have assigned to it the file page-tips.php selected as its custom template.

Template Name: Tips Page Template

You can assign a Template to a WordPress Page using the Settings in your Page editing tools.

Page ----> Settings ----> Summary ----> Template ----> Select Template from Dropdown

But what would happen if I was to move this file from the Themes root director to the pages directory that we just made?

mv page-template_archive.php /pages.  [move file to pages directory]

When the file has been moved, go to the page editing tools and refresh the page in your browser.

You’ll see that the WordPress page you previously had assigned to page-template_archive.php has reverted back to “default template” and the one we previously assigned has not been recognised.

Move page-template_archive.php file back to the root directory and refresh the admin page again.

You’ll find your original Template selection is back in place.

The bottom line is that Custom Templates need to exist in the root directory on your WordPress theme to be recognised by WordPress. This means that the pages directory is redundant and can be deleted.

Instead, we should organise our custom templates with a suffix of page-[template_name] in the filename so you can identify them as a custom page template.

page-template_archive.php

Parent Page Templates

Parent Page templates are how we can set up page hierarchies in the admin area. With such directories, WordPress categories will indent links to the pages that represent pages that have a parent template.

First, create a new Page in the admin area and give it a title.

Add Page - (Page Title: Template Search)

How to set a parent template

We can create as many custom templates files as we need to and either assign one page to each template or multiple pages to the same template file. To do so, WordPress provides a tool to select a template to be its parent, with a Page Attributes section.

Settings ----> Page Attributes ----> Parent ----> Select Template

With this technique, we can add unique content and page designs to as many pages as we need.

We can add custom code to templates like this…

<article>

    <div class="custom_page_template">

        <h2>Search Template</h2>

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

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

                    <!-- Content that loops goes here --->
                    <?php the_content(); ?>

                    <!--  <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a> </li> -->

                <?php endwhile; else : ?>

                <!-- The loop ends at this point -->
            <?php endif; ?>
                        
    </div>

</article>

Or even introduce different classes to the same element for slightly different style themes.

<article>

    <div class="custom_page_template style_one">
    </div>

<article>

<article>

    <div class="custom_page_template style_two">
    </div>

<article>

Each of these pages should have it’s unique “slug”, a string that goes on the end of a URL so you can link to it in your navigation or template files.

slug: template-search template-search

Template Parts

With Template Parts, you can organise code blocks into separate files which can make themes easier to maintain and your code more readable. We’ve already seen an example of this with the header and footer templates.

<?php require "header.php"; ?>

<?php require "footer.php"; ?>

Here, we’re using the require keyword to retrieve the contents of another file and use it in the current one. Filenames and directories are always relative to the current file.

There is another way to use component files in WordPress.

<?php get_template_part();

As the name describes, it is a function specifically designed for template parts within themes. We use it to load smaller template parts into main template files. It helps keep the code organised and modular.

<?php get_template_part( 'partials/content', 'page' );
get_template_part( 'assets/template-parts/main', 'nav' );  ?>

or

<?php require("assets/template-parts/main-nav.php"); ?>

To use this function with subfolders in your theme directory, simply prepend the folder name before the slug. For example, if you have a folder called “partials” in your theme directory and a template part called “content-page.php” in that sub-folder, you would use get_template_part() like this:

<?php get_template_part( 'assets/partials/content', 'page' );  ?>

So to summarise, what the function does is link to the template hierarchy and has less intrusive error handling in development and assumes it is a relative path to a PHP file. The require keyword does not follow the WordPress theme hierarchy. This means that you must specify the exact path relative to the origin file.

A brief tip about parent and child themes

Parent and Child themes – There’s scope for an entire blog on this but essentially what we’re talking about here is one theme directory and another theme directory within it; one that inherits from the parent. A parent theme is a complete theme that has everything a theme needs to work as a Theme on its own. It can function independently and is a fully designed theme on its own.

A child theme takes inheritance from its parent. This allows developers to modify or add to the functionality of the parent theme without directly editing its files and removes the danger of making breaking changes to a Theme design.

A tip for theme file organisation

The rest of it is very simple and about how you choose to organise development files, that is to say images, stylesheets, script files or any other file that is not a PHP template.

Theme files should essentially follow this structure

• One or more directories ( e.g. assets (d) )
• index.php (required)
• functions.php (required)
• style.css (required)
• screenshot.php (required)
• Other Template files (.php) with regard to the Template Hierarchy

I like to use an assets directory where I’ll keep Digital Image files like Photoshop files, PDFs and Wireframes and more, so that everything I need to develop my theme is in is in the same place.

• Assets
  • sass
  • images
  • static
  • template_parts
  • scripts

You would not need to upload this folder to the server with your theme so long as you keep backups of the directory in local development.

• dev
  • styles/
  • scripts/
  • template_parts/

I also have a development folder where I put images, styles and scripts that are to be uploaded to production servers.

So to summarise as we come to the end of this post, what we have is a set of files organised in the root directory according to the needs of the hierarchy. We have talked about 2 directories that go into the theme called “assets” and “dev” allow us to easily find our design and development files when we need to. And lastly, we’ve discussed how to use and organise our Custom Page Templates.

I believe we have enough information now to start talking about database migrations.. so we can move our database files from one local location to another and then from local development to a web server. Join me for that in the next blog.