WordPress Theme Development single.php

You’ve got your WordPress Project up and running. Now it’s time to learn how to customize a WordPress theme to make it look the way you want.

Out of the box, WordPress is bundled together with 2 or 3 separate designs that you can use called “Themes”.

If you wanted to, you could choose one of those designs, “activate” it and start developing your project right there and then. But we’re not going to do that. We’re going to learn how to make our own theme.

For a WordPress theme to work, as a minimum, we need the following files.

• index.php
• functions.php
• style.css
• screenshot.png

That doesn’t sound like a lot but it’s worth taking time to explain what each file is for.

index.php – This is the catch-all template. If there is no other template, every page you look at will display what is on index.php. There will be plenty of time to talk about how to make WordPress display what you want when you want it, but this single file will do for now.

functions.php – This file is where we run the functionality of your theme, and do important maintenance and operational tasks. For example, these will be things like enqueuing styles and scripts to make your site beautiful and functional, opening up support for Widgets and Menus or customising post pagination.

style.css – As you may have guessed, this file is where you put all the styles in the stylesheet. If you are using Sass to write your styles you need to make sure that the output stylesheet is called style.css.

However, it also serves another important function. The style.css file has to include a comment header so that WordPress has access to what it needs to know identify and activate your theme.

e.g.

/**
 * Theme Name: JGDM Subdomain (2024)
 * Theme URI: https://wordpress.jonniegrieve.co.uk
 * Description: Update to the WordPress Subdomain for JGDM where I guide users how to build a theme as I go.
 * Author: Jonnie Grieve (@jg_digitalMedia)
 * Author URI: https://www.jonniegrieve.co.uk
 * Version: 1.0
 * License: GNU General Public License v2 or later
 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: subdomain_2024
 */

Screenshot.png – Finally, your theme needs to include an image file (.png) that is kind of like a promotional, or identfying in the WordPress Theme Repository.

Go to Appearance ----> Themes

When you have all of these files in place you have a working WordPress theme. See how in the WordPress directory you can see some of the details of the theme from the example comment header.

Getting access to the dashboard via the admin bar

Let’s start developing in earnest.  I’m going to modify the index.php template by including a reference to 2 new files; header.php and footer.php.

In your localhost page, you’ll see something like this

Warning: require(header.php): Failed to open stream: No such file or directory in<br>C:\xampp\htdocs\theme_directory_name\wp-content\themes\theme_directory\index.php on line 1

This is a standard warning message that is just letting you know it hasn’t found the template files yet – because there’s no file found in the file path, relative to the location of index.php.

Create your header.php and footer.php files.

<?php

// header.php 
echo "header.php"; ?>

<?php

// footer.php
echo "footer.php"; ?>

Now we can see that both the footer.php and header.php are being loaded because we have placed all 3 files in the same directory.

We’re now ready to make the admin bar accessible. We do this by using a 2 functions in the header and footer files.

<?php wp_head(); ?> – This method is used by WordPress plugins and the WordPress core to insert crucial elements into your document (e.g. scripts, styles, and meta tags). Always put php wp_head(); just before the closing tag of your theme (usually in header.php): To reiterate, this method allows WordPress to hook into code and output CSS, JS and HTML needed, so it can echo out the different values for each page.

There’s another method that goes in your footer.php template file.

<?php wp_footer.php();  ?>

The main purpose of this method is to open up access to the admin bar so that you can access the administration tools whenever you are signed into your website as an administrator. You get the same bar with other user levels as well, but what you have access to, depends on options the administrator has given you.

Populate your CSS File.

Remember that you only need one stylesheet file to implement all the styling for your project. So you can either develop your styles directly into the stylesheet. The alternative, which is what I like to do is to use the Sass precompiler to generate your output stylesheet.

sass --watch sass.scss:style.css

You can keep it as simple as possible with a single Sass file.  But in this example, what I’m doing is working with 4 new files.

sass.scss – where I write 3 @import directives. The _head.scss partial is where I’ll put the WordPress Comment header.  I like to keep at least one separate file for storing Sass variables and that’s what config.scss is for.  And then I’ll put the bulk of the styling in _main.scss.

/* main.scss */
/* config.scss */

I like to put these Sass files into their own directory called “assets”. For the import directories, I use file paths relative to the location of style.css.

/* sass.scss */
@import "assets/sass/head";
@import "assets/sass/config";
@import "assets/sass/main";

Assuming we’re still watching for changes with the sass –watch command, we can now start making changes to the stylesheet.

body {

    background: mediumaquamarine;
}

Each time Sass detects that keystrokes have stopped, it will generate a new version of style.css with those changes.

Enqueue Scripts and Styles

So at this point, we have set up our stylesheet with Sass and made sure that WordPress is primed to accept scripts and stylesheets. But you may have noticed that the change we made to the background colour of the body element has not come into effect.

Let’s talk about why this is and how to fix it.

You can’t link to your stylesheet in the same way you would if you were doing it in an HTML or PHP file. WordPress would just keep looking for the file and not find it in the way it expects. It only looks inside the theme directory and does not take any queues from HTML files you might have created. We need to enqueue the stylesheet and scripts from within, inside functions.php. Enqeuing is what tells WordPress when and where to load your files.

// ENQUEUE ASSETS
function enqueue_main_stylesheet() {

    wp_enqueue_style ('main-css' , get_stylesheet_directory_uri() . '/style.css', [] );
}

add_action( 'wp_enqueue_scripts','enqueue_main_stylesheet' );

Don’t forget to use the wp_head() function as the last code used in header.php.

But assuming that’s in place, the above code should be enough to change the styling. How does it work?

We’ve defined a function named enqueue_main_stylesheet() that will enqueue the stylesheet. There are a few parameters on display that will help this happen.

• The handle/name of the stylesheet (‘main-css’ in this case).
• The URL of the stylesheet, which is obtained using get_stylesheet_directory_uri() to get the directory
• URI of the current theme, and then appending ‘/style.css’.
• An optional array of dependencies, which is empty ([]) in this case.

Below we’re using a separate function below to enqueue a JavaScript file.

function wp_enqueue_main_script() {

    wp_enqueue_script( 'script-name', get_template_directory_uri() . '/app.js', array(), null, true );

add_action( 'wp_enqueue_scripts', 'wp_enqueue_main_script' );

Despite the name, it is used for enqueuing both scripts and styles. I’ll now talk briefly about the parameters the wp_enqueue_script() takes.

• First, a string handle – This is a unique identifier for your script. You can use it to order script files in your project if you need multiple file, for example including jQuery.
• Full URL of the script, or path of the script relative to the WordPress root directory. getget_template_directory_uri();  makes it portable because it gets the relative URL wherever it happens to be on your system.
• An array of registered script handles that the current script depends on.
• Version number – If set to null, no versioning is added.
• An array of additional script loading strategies. e.g. defer or async
  Whether to print the script in the footer. Default ‘false’.

Start converting Content

Either you’ll be starting from scratch, or more typically you’ll be copying markup over from static HTML or PHP files you created as drafts.

Start by mirroring your file structure from your draft files to your WordPress theme.

e.g. wordpress_theme
   \assets\sass
        _config.scss
        _head.scss
        _main.scss

When you’ve made sure that the files and copied code are in place, and that you’re in the appropriate directory for your theme, generate a new stylesheet with the sass --watch command.

-> subdomain_2024/wp-content/themes/subdomain_2024

sass --watch sass.scss:style.css

I’ll finish this post by talking about porting over your markup from your draft files over to your theme.

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

<?php echo "index.php"; ?>

    <h1>WordPress Theme Development <span class="template_name">front-page.php</span></h1>

    <section>

    <article>

        <div>

            <h2>Working with WordPress</h2>
        </div>
                 
    <!-- . . . --> 
                 
    </section> 
   
    <?php require "footer.php"; ?>

You might run into some problems if you’re already using some PHP methods or using template parts that you haven’t copied over. So make sure you’ve accounted for every piece of markup that you need to by either creating new files or copying them over from your drafts.

Warning: require(assets/template-parts/main-nav.php): Failed to open stream: No such file or directory in C:\xampp\htdocs\wordpress\subdomain_2024\wp-content\themes\subdomain_2024\header.php on line 20

Fatal error: Uncaught Error: Failed opening required 'assets/template-parts/main-nav.php'

So in my case, I copied over the code from the main navigation template part which keeps my navigation in one place.  e.g. you can have a HTML list of links like this:

<!-- main navigation -->
<nav>
    <ul>
        <li><a href="index.php">Setup</a></li>
        <li><a href="home.php">Blog</a></li>
        <li><a href="single.php">Single</a></li>
        <li><a href="tips.php">Tips</a></li>
        <li><a href="page-template.php">Templates</a></li>
        <li><a href="page.php">About</a></li>
    </ul>
</nav>
                             

We’ll stop there at this point. We’ve made a lot of progress culminating in a WordPress theme that has a full-fledged page that looks like it is part of our custom design. We have enquired about all the styles and assets. We can access the WordPress dashboard and can select our theme in the WordPress repository whenever we want.

The next thing to do is to create our WordPress menu and add more pages and Templates to our WordPress Theme.