My First WordPress Theme Build — Part 1

Working with a “starter theme” and enqueuing javascript libraries

Why create a new theme rather than work with what’s already available?

I’m generally not a fan of reinventing the wheel and needlessly re-writing code is one of those things.

I’ve worked with WordPress for several years and I’ve always altered the themes using child themes. There were things that I’d always code into the child themes to make them more customizable and easier to update.

After creating different workflows I realized I wanted to create something that users could easily download and modify without having to write additional code. On the creation side of things, I want to see if it might be better to create a theme rather than work with existing theme for my particular purposes.

I’m not sure if building a whole theme will turn out to be the best idea, but, hey, it’s an experiment! :)


What do we need in a theme?

For this new theme, which I’m calling Copernicus, the first thing I wanted do was to create the basic file structure for the theme.

There are three main types of files in a theme: stylesheets that control the visual design and layout; template files that show how pages should be generated; and a functions file (functions.php).

Basically, the only files you need to include are style.css (the stylesheet for how things on the site) and index.php (which typically lists post excerpts). But that would make a pretty boring site.

Typically, we include template files like comments.php, comments-popup.php, footer.php, header.php, and sidebar.php, as well as functions.php which dictates many of the behaviours of the website.

Within PHP files like index.php, we would call other files by including code like:

<?php get_sidebar(); ?>
<?php get_footer(); ?>

This keeps things modular and ensures that changes to footer.php extend to all pages on the site simultaneously.

There are also template files that dictate how pages are displayed. These are PHP files that you can descriptively name. For instance, in your theme directory, you can create “2col-template.php” and give it a name using the following code:

<?php
/*
Template Name: 2 Column Template
*/
?>

You can then call other PHP files and add code to build the template how you want. Templates can be enormously powerful.


This isn’t just a child theme, but let’s not build everything from scratch!

It’s all well and good that we now know what files we need, but I really don’t want to start from scratch if I don’t need to. So, I found a “starter theme” called underscores, which include all the typical files you’d use in a WordPress theme and is designed to be your base code for hacking together a theme. Underscores also came out with a service earlier this year called Components, which provides some starter theme options.

You can basically enter the name of your theme, and underscores will create all the files you need for the theme in an easily downloadable ZIP file.

To upload the theme to your site, go to your WordPress dashboard, click “Appearance”, choose “Themes”. Click “Add New”, then “Upload Theme” and “Choose File”. Find your theme ZIP file (likely in “Downloads”), then upload it.


We’ve got our theme files, but now we need some javascript libraries

To add advanced functionality to your website, you’re probably going to want to add some javascript libraries that let you use pre-built functions.

In a regular HTML website, calling javascript libraries is as simple as typing:

<script type=’text/javascript’ src=’[location of javascript library]’></script>

But because WordPress has a lot of working parts, it needs to be careful about when libraries are called. Its system requires users to “enqueue” scripts they want to use. This is done using the wp_enqueue_script function in the functions.php file.

This is the structure of wp_enqueue_script:

wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );

For my purposes, I wanted to use the jQuery library. Many common javascript libraries are actually included in WordPress. This is the case with jQuery, so you downloaded the jQuery file when you installed WordPress — you just need to find out where it is to get the $src argument.

By going into the files, you’ll see that jquery.js is in wp-includes/js/jquery.

You don’t want to hardcode the URI of jquery.js because it will be different for every different site, so you need to use the get_stylesheet_directory() function in WordPress. Basically, this gets the path to current theme directory, to which you can append the rest of the pathway to jquery.js.

For my site, the code “get_stylesheet_directory() . ‘/js/jquery/jquery.js’” outputs “http://copernicus.wpengine.com/wp-includes/js/jquery/jquery.js?ver=1.12.4

So, now that we have the right pathway for the jquery.js file, we can build the function.

This is what my enqueue script for jQuery looks like:

wp_enqueue_script( ‘jquery-core’, get_stylesheet_directory() . ‘/js/jquery/jquery.js’, ‘’, ‘’, true );

Now, where do I place this?

Basically, you want to do a search in the functions.php file to find where the other wp_enqueue_script calls are, and add your javascript calls to the same function.

This is where it fits in the code that underscores provided me (see line 111):

If you use underscores, you’ll see this function as [YOUR THEME NAME]_scripts.


So, now I’ve got jQuery working in my theme, and I’m going to add a few other javascript libraries just to make my theme development easier.

In the next few posts, I’m going to be incorporating a grid system, adding widget areas, and styling templates. I’m going into my first full theme project with equal parts excitement and trepidation — hopefully you’ll find my successes and failures useful as you attempt a theme build or simply want to learn more about the inner workings of WordPress. :)

David Hamilton

PS — Let me know if any of these instructions are confusing and I’ll update the document to be clearer and more useful.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.