heavily edited/contributed to by: Michelle Schulp

In part 2 of this series we ended having made a header.php, footer.php, and template-part/post-loop.php to show our most recent posts on index.php using The Loop. In this article we’ll work on displaying some additional useful WordPress data within The Loop, adding a sidebar, and create additional markup and styles for structure.

In the interest of diving right into displaying your content, we also skipped some very important elements that WordPress is looking for. We want to add wp_head() and wp_footer(), which are known as action hooks. We’ll talk about the concept of hooks later, but for now what you need to know is that these specific hooks enable themes, plugins, and WordPress Core to output content into the header and footer, respectively. Luckily, it’s very simple to include them now:

First open up your header.php file and find the the closing </head> tag. Just before this tag we are going to add the php function wp_head() so header.php should now look like:

wp_head() allows themes, plugins, and WordPress Core to add links, scripts, and other output to the header. If you’ve noticed in your browser inspector, while we do have a style.css file, it is not actually being called or used in our HTML markup yet – but don’t worry, we’ll be getting to that today.

Similar to wp_head(), there is also the wp_footer() function, which I’m sure you hvae already guessed goes in footer.php. Open this and add it right before the closing </body> tag, and your file will now look like:

wp_footer() basically does the exact same thing as wp_head(), allowing themes, plugins, and WordPress Core to add scripts and other output to the footer of our theme.

Adding markup within the loop

Let us turn our attention back to template-parts/post-loop.php which currently only has <h2><?php the_title(); ?></h2> in it. Remember, this is the content inside our Loop, which is output for each post we have. We probably want to display something besides the title, perhaps we want to show who wrote each post and the post content itself. In anticipation of our new content, let’s give it some basic markup so we can target it with styles later. We’ll start by wrapping everything in an <article> tag as well as adding two more empty <divs> under the <h2> title – give the first <div> the class of author and the second the class of post-content. The file should now look like:

WordPress provides us with a number of functions to help output our data. According to WordPress standards, any of the core fucnctions that start with the_ will automatically output (echo) the information being returned, which is why they are often used in themes to display content. The two that we will use now are <?php the_author(); ?> and <?php the_content(); ?> – I’m guessing you have a pretty good idea what they do! Place each of these funcitons inside the appropriate <div> like:

When you refresh your page, you should now see a list of titles, authors, and the entirety of the post content (including any images or media embedded within the post).

Adding WordPress IDs and Classes

WordPress also has some very handy helper functions that will be beneficial when we want to target these elements with CSS or JavaScript. WordPress themes typically allow us to target content via unique classes that each page or post has. To allow for this we will update the opening <article> tag to look like:

Here the_ID() will display the specific ID of each post. post_class() creates the class= and displays a number of automatically generated classes WordPress creates to target different post types. Because we added our own specific class to the output, we put it inside the function like so: <?php post_class( 'post-archive' ); ?>.

Go ahead and make sure everything is saved and refreash your site. Some default browser styling should now take effect due to the <p> tags that the_content() function automatically adds to your content. Take a look in the browser inspector to see the IDs and classes that WordPress has added to each article.

Enqueue stylesheets: our first look at actions

Ok – lets move on to doing a little styling work. First of all, we need to make sure WordPress recognizes that we have a stylesheet and knows where to use it. This will take advantage of the wp_head() function we added earlier.

The correct way to include stylesheets in WordPress is to enqueue them . We do this by adding a function to functions.php as seen below:

Let’s break this down so we can see what’s actually happening.

First we see a function called add_action – this is a core part of how we work with WordPress, and our first experience hooking onto an action event. We are basically telling WordPress “When the specified action happens, add the stuff from my function here as well.”

We send add_action two arguments. The first, wp_enqueue_scripts is the name of an existing action hook or a place where WordPress expects stuff to happen. The second argument, my_cool_theme_scripts is the function name containing what we are going to do (which we see referenced below).

To think of this another way, imagine a scenario of deciding to hook a “buy milk” function to the action “at the store”:

This is saying “When I am at the store, in addition to what would normally happen here, I would also like to buy milk.”

Back to our function, underneath add_action you see the my_cool_theme_scripts function itself. Don’t let the word scripts confuse you here, you can call the function anything you want as long as it’s referred to correctly in our add_action call. Just remember, it is very helpful if your function names are descriptive. Since stylesheets and JavaScript are often added at the same time, it’s common to see them enqueued in the same function.

Ok, so inside our my_cool_theme_scripts function you’ll see yet another function from WordPress Core called wp_enqueue_style which is used by WordPress to add the stylesheets to the header (via wp_head()). This function is also getting two arguments.

Here the first argument is the handle of our stylesheet. All you need to know right now about this is that it should be unique so it is often prefixed (i.e. just add your theme name to the beginning of the handle). The second argument is the actual location of our stylesheet. WordPress has another helper function get_stylesheet_uri() which literally looks for the file style.css in the root of your theme – so in this case this is all we need here.

Side notes on functions.php

This is where I start to be opinionated about how themes should be built. You’ve noticed that I told you to add this code to functions.php, and you will see many other tutorials talk about placing code here. Technically, that is all correct, because all functions placed here will work as expected. However, we are not just writing code that functions correctly, we are trying to write code that is easy to edit, maintain, and update, so we should be thinking about code organization at all times.

For proper code organization Functions.php should be a file that only includes WordPress Core functions that set up your theme, such as enqueuing styles and scripts. All other functions, like custom functions or helper functions, should be placed in other files, and referenced here via a require_once() call. Using this approach, your functions.php file will remain shorter and easier to navigate, while any files that you will eventaully require_once() in functions.php will be much easier to navigate and read as well.

If this is confusing at this point, that is perfectly fine. In our next article, we will be creating a custom query where this principle will be demonstrated. For now, functions.php is just fine the way it is.

Adding styles and structure

Let’s revisit our style.css and add some styles to give our theme a little bit of structure.

You can fill the rest of the information out if you like, since it does show up on the Appearance > Theme interface, but it is not required for us right now.

If you know a little about CSS, you can include your favorite resets and other structural components in your file now, underneath the WordPress information. Remember, this is not an HTML or CSS tutorial, the examples here are just to show you how the structure works in conjunction with WordPress, so you may have a different way you prefer to markup or style your themes, and that is fine!

At minimum, we want to include something like the following:

We can also write styles that target the elements we’ve introduced into our theme. Just for fun, in order to show that our styles are loading properly, add this as well:

If everything has gone well (and you’ve saved style.css and functions.php) when you refresh the frontend of your site you should now see our basic styles taking effect. Look at those attractive green titles! Of course, you can style your text and existing elements however you like.

Sidebars!

Many WordPress themes include sidebars. These can be used as “widget areas” to output the content found in Appearance > Widgets or can be used to output custom content. We’ll be learning how to do both.

Let us start by making room for our sidebar. Depending on the theme, you may want to include the classes for wrapping the content and sidebar in your header and footer. However, if you don’t want to include the sidebar on every page, this is not recommended. For now, we will add this logic to index.php as this is currently our only page template.

Our first step will be updating index.php to include some new markup. Remember to properly open and close your PHP tags!

You can see that we have created two content areas, a main <section> for our post content, and an <aside> which will contain our sidebar. Next we need to create a template file for our to-be sidebar. Create a file called sidebar.php and place it into the main theme folder. Then update index.php to this:

The WordPress function get_sidebar() automatically looks for sidebar.php in your theme root folder. Feel free to add some random text inside sidebar.php, like “This is my sidebar,” so we can make sure it is loading correctly. If it is loading you should see your random text showing below the list of our posts. Why is it showing up below? Well, right now all of our block level content (like <div> <article> <section> and <aside>) defaults to 100% width.

In order to get the sidebar to show up to the right hand side of the content, go ahead and add this to style.css:

Feel free to use your favorite CSS method for aligning content if floats are not your thing. We’ve added a border and some padding to the .content-right class so we can distinguish it from our main content. Refresh your page after saving style.css and you should see content to the left and a (short) sidebar to the right. This is starting to look like a website!

Once your sidebar.php file is loading correctly, we should populate it with some real content. If we want to use this sidebar to display widgets, we need to register the sidebar so WordPress knows it exists. Open functions.php again and add the following:

Remember, because this is a theme setup function, it is OK to include in functions.php. We won’t go into too much detail here about what each component is doing, but if you want to learn more about registering sidebars/widget areas, visit the Codex or GenerateWP.

Once the sidebar is registered, it will show up in Appearance > Widgets and you’ll be able to add widgetized content to this area. Go ahead and add a couple of the core widgets to this sidebar now. However, they won’t get show up in your theme, because we haven’t told our sidebar template to display them yet.

After you’ve got some sample widgets in place, you can return to sidebar.php, delete your sample text, and insert the following:

The dynamic_sidebar() function tells your theme to display all of the widget content contained within the sidebar ID you are referencing. Themes can have multiple widgetized areas which can output content based on various rules, but for now we’ll stick to just one. When you refresh, you should see those widgets inside your sidebar.

Though sidebars are often used for widgets, we can also write our own custom functionality for content that is displayed in the sidebar. As an example, let’s go back to our list of posts. We want to add another default loop above our dynamic sidebar and output some titles. In your template-parts folder, create a new file called sidebar-content-custom.php and update sidebar.php with a call to that template part:

Inside sidebar-content-custom.php place the following to output your post titles:

Now you should see a list of the titles of the same recent posts in the sidebar that you are seeing in your main loop, above the dynamic sidebar content. This is a good place to stop for now. In our next post we will customize the output further by digging into writing custom WP_Query and learning how to customize what it returns.

If you’d like to have a look the theme files as they should appear now please head over to Github here and download them

edited/contributed to by: Michelle Schulp

Where we are at

Ok, so in our last post, we finished with you creating and activating your own WordPress theme, but the only thing it did was say “This will work” on the home page. In this post we will add a header, footer, and output a basic list of posts on the home page using the default WP_Query and Loop.

So fire up your local environment and lets get to work!

Base Structure

All websites have a header and a footer (even if they appear not to). The header includes the doctype, the opening <html> tag, all of the information contained within the <head> tag, and the opening of the <body> tag. Sometimes it also includes navigation, the site logo, or other components found at the top of every page. The footer includes your <footer> tag and the closing of the <body> and <html> tags. Many websites also have <divs> that function as content wrappers, and encase all the content on every page.

Lets start by creating a header.php and a footer.php in the root of the <your-theme> directory.

In these files, simply type the words “header” and “footer” respectively, so we can see that they are loading in our next step. Now that these files exist, we need to tell your theme to load them. WordPress has functions that specifically look for these files, so in index.php we will add two Core functions that call (i.e. include) these files. These two funtions are get_header() and get_footer() – when you add these your index.php file should now look like:

After saving and refreshing your home page you should now see headerThis will workfooter.

Adding some structure

Ok, this is all well and good but we need some html to make this thing actually work. Lets take this basic html structure and decide what will be in header.php, what will go in index.php and what will be in footer.php:

In WordPress themes, we always want to avoid repetition in our code by breaking it up into reusable parts whenever possible. This means when planning what will go in our header and footer, we want to identify the components which will be exactly the same at the top and bottom of our pages.

So let us consider what will be common to every single page on our site. Clearly every page will need our doctype, <html>, <head> and, <body> tags but we can take this further be saying that every page will also need the div.wrapper and div.content opening tags. Go ahead and paste all these in your header.php (delete anything that may still be in this file) file which will now look like:

Clearly all these will also need to be closed, so take everything else and paste it into footer.php (delete anything that may still be in this file) which will now look like:

Make sure you save both those files, then refresh your site and view it in the inspector (right click > Inspect in Chrome). You should now see these html tags being output at the top and bottom, and your “This will work” content in the middle. Note: there is some more content we will need to add to the header and footer for WordPress to work properly, but we will get to that in the next tutorial.

Digging into The Loop

Ok, we now have some stucture and can begin to start diplaying our posts. To start with, delete your sample “This will work” content in index.php. We will also update our php here to be a little cleaner by eliminating extra opening and closing tags:

Note that there is no close php tag ?> at the end of this file. We don’t actually have to close php at the end of files, and not doing so can help avoid common white space issues that result in a “headers already sent” error.

Now that this is a little cleaner, we will update it to include the WordPress Loop. “The Loop” is one of WordPress’ core capabilities which is used to output your post data (aka, show the content on the frontend of your site). In combination with WordPress core templates, WP_Query and a few other custom functions, this is a powerful tool that enables you to display any combination of WordPress content, and powers most of the visual logic of themes.

For now, we will use the default Loop with no special query defined, which, on index.php, outputs all recent content from “Posts.”

Let’s break this down and understand what’s happening:

1. if ( have_posts() ) { checks if we actually have any posts to display.
   By default, WordPress assumes that your index.php file is supposed to show a list of your most recent posts, and because we grabbed all that Unit Testing Data to populate our site with content, we should have posts to display. You can read this as “If we have posts.”

2. Then while ( have_posts() ) { will loop through all our posts that we are supposed to show.
   Read this as “While we have posts to show, do this thing for each post.”

3. the_post() is a very important function which is often forgotten about when starting to work with WordPress.
   This function sets up the current post’s information so we can use WordPress’ core functions. Read this as “Use this specific post information for the following content.” In this example the next function we call is the_title()

4. the_title() Unsurprisingly, displays (or echoes) the name of the current post ( the_post()) in the loop.

If everything has gone correctly so far, when you refresh your site’s homepage you should now see the titles of the first 10 posts from our sample data. Why 10? “Show 10 Posts” is the default setting in WordPress’ Settings > Reading page for the maximum number of posts that can show on a single page. If you update that setting, it will change the maximum number of posts output in any loop/archive. (You can also customize how many posts-per-page appear programmatically with a custom WP_Query, but this setting can have affects on pagination if you ever try to display a posts-per-page number that is larger than what you set here, so just be aware of it).

WordPress by default also assumes that you only want to show Published posts, so any Scheduled or Draft (or anything that is not Published) will not be displayed.

Adding template parts

So we have a list of titles being spit out (in a very ugly way, remember we haven’t added any styles or markup yet). However, that is probably not very useful content in most situations. We can display all sorts of WordPress content here, like your post content, the author, the date, any taxonomies associated with the post (like categories or tags), any metadata associated with the post, featured images, etc. And you will probably want to wrap this in semantic markup so that you can style it as well!

We could just write all of that stuff right there inside the Loop and it would work. But remember, it is good practice in WordPress themes not to repeat yourself, and keep logic separate from visual presentation as much as possible. Maybe we will be displaying posts with the same formatting in multiple areas of the site, or maybe we just want to simplify our index.php file and make it easy to find the code for our single post content later. This means we probably want the code for our single post content to be in its own file.

This is where Template Parts come in. Much like how get_header() and get_footer() tells WordPress to go look for specific core template files, get_template_part() tells WordPress to look for specific custom template files, and it’s a good idea to get in the habit of building Template Parts for each unique section of your content.

Let’s start making our first Template Part, which will contain the block of HTML for each of our posts.

Go ahead and delete the_title() from index.php and add get_template_part( 'template-parts/post', 'loop' ); in its place. WordPress’ get_template_part() function starts looking for files at the root level of your theme (i.e. at the level where index.php is). In our code, you can see that we are passing 2 strings (i.e. text) to this function. The first string template-parts/post tells WordPress to look for <your-theme>/template-parts/post-<em>.php where </em> represents any additional string, while loop tells WordPress specifically to look for post-loop.php. This means it is looking for a file called post-loop.php inside a directory called template-parts.

These don’t exist yet, so clearly we need to create this directory and file. Add a template-parts directory to your theme and create the file post-loop.php inside of this new directory.

Once this directory and file have been created, go ahead and add <?php the_title(); ?> to our new template part.

So now index.php looks like:

And our new template-parts/post-loop.php should have just one line of code like:

To take this one step further, let’s add an html heading tag around the_title() like:

Note how the html is outside of our opening and closing php tags ( <?php and ?>).

Now refresh your site, and you should see all the titles of your first 10 posts now being displayed as <h2> headings.

This is a good place to stop for now. In our next post, we will add some of our posts’ content, as well as add to the html structure so we can get some basic styles in place.

If you’d like to have a look the theme files as they should appear now please head over to Github here and download them

edited/contributed to by: Michelle Schulp, Maura Teal, Kyle Maurer, and Ben Meredith

This series will teach you what you need to know to build a simple WordPress theme. We’ll be starting with the basics of local development and WordPress theme structure, and moving into learning how WordPress outputs and processes information, before finally learning how to combine that with HTML/CSS to produce a final theme. We will not go over every single use case, but my hope is that you will learn enough from this series to be able to do your own research, ask the right questions, and read/understand other people’s code as well.

One assumption I am going to make is that you already know how to install themes and plugins, navigate the admin area, work with menus, and make content changes – if this does not describe you, take some time to learn these topics and come back when you are comfortable navigating the admin of WordPress, and familiar with how themes/plugins interact with it.

Another assumption is that you are already familiar on some level with HTML/CSS. Though markup and styling are important to the visual presentation and organization of themes, as well as other considerations like semantics and accessibility, we will not be covering those topics in-depth here. There are many resources available for getting yourself familiar with these things, and if you are not, I suggest doing so before reading the later articles in this series.

Local development

Before we get started, you need to have a local environment up and running – this is crucial to anyone that wants to work with code because you (and I) will break things, and it’s a lot easier to deal with/fix that on your own computer

Should you not have a local environment, take a look at these links to get started setting one up:

• https://developer.wordpress.org/themes/getting-started/setting-up-a-development-environment/
• https://serverpress.com/get-desktopserver/ (beginners)
• https://www.apachefriends.org/index.html (intermediate)

Now, if you are new to development, you’ve probably spent the better part of your day getting your local environment up and running, probably swore a lot, and want to go all ‘Office Space’ on your computer. This is ok – feel free to take a break and come back to this post later – it’s not going anywhere. 😉

Code editors

If you are going to be writing code, you’re going to need a text/code editor. If you don’t have one currently, head over to http://www.sublimetext.com/2 and download Sublime Text – it’s free (though it will bug you for a donation every 10 saves or so). Personally, I use Sublime Text everyday and love it. You’ll also hear of developers using PHPStorm or Coda – both of which have their benefits. We don’t need to discuss the merits of text editors vs IDEs right now – a feature-rich text editor like Sublime Text will be more than enough for what we are doing during this series.

Why am I not starting with a child theme?

A Child Theme refers to a theme that is dependent on a Parent Theme for operation, it cannot exist on its own. The advantage is that it lets you modify the Parent Theme without altering it, so if the Parent Theme updates, you will not lose your changes.

Child themes work by containing template and style files that override the equivalent files in the Parent Theme, or extend the Parent Theme with new files. They fall back to using a Parent Theme’s code and layout for templates/styles not defined in the Child Theme. This could be as simple as just adding a few new items to a stylesheet to override a Parent Theme’s CSS, or it could be complex with dozens of new templates, scripts, functions, etc.

Child themes can be a great way to learn about how to modify theme files, and many people start this way. However, I’d like to give you an understanding of exactly what goes into a theme and why, and that’s easiest to do when we start with a blank slate and build up from there. This knowledge will help you build Child Themes as well as Parent/Standard themes in the future.

Looking at WordPress

But let us pause for a moment and look at what we are dealing with so far. At this point you should have WordPress installed locally, so navigate over to that directory/folder now on your computer, it should look like:

wp-admin, wp-includes, and the .php files here are considered the Core files. We will almost never be touching these (that would be considered modifying/”hacking” core) unless we need to alter or create a wp-config.php file. Our work will happen in wp-content/themes, so navigate there now. Here you should see something like:

These folders are the default themes that come with a WordPress install.

Take a break at this point and make sure your local install is working correctly by opening your browser and going to the frontend (meaning how the website looks in your broswer, on whichever URL is specified by your local development environment) and poking around. If the theme is loading at all, we should be good to go.

What a theme needs to come alive

A theme needs 2 base files to be considered operational.

1. style.css (your main styles and where your theme is defined)
2. index.php (the default template for displaying content on the frontend)

Many themes also have functions.php (default file for adding functionality), but it is not necessary for a theme to exist. However, we will be including one in our theme.

Let’s take a look at twentyfifteen’s style.css. Open it up in your text editor. The top of the file should look like:

Now humor me for a second and activate the Twenty Fifteen theme if it is not already. Ok, now take that style.css file (which you have open) and change Theme Name: Twenty Fifteen to Theme Name: My Cool Theme. (No, it’s not generally a good idea to directly edit other people’s themes, this is just for demonstration purposes). Save the file, then head back over to Appearances > Themes, and Huzzah! the name displayed here should now be My Cool Theme. This is what I am referring to above when I said “Where your theme is defined”. WordPress requires that a style.css exist in the root which has this special header area, and tells WordPress “This is a theme.”

“Ok, Ok, that’s kind of cool” you say, “but I want to build my own theme!”

Fine, let’s get started.

In wp-content/themes create a new directory/folder, name it whatever you like, maybe my-cool-theme (from here out I will refer to your theme directoy as Note the directory should not have any spaces in it). Create the three files that we will be using: style.css, functions.php, and index.php. Once that is done, copy the header code from the Twenty Fifteen style.css (that we just looked at), and paste it at the top of /style.css – note: make sure to rename Twenty Fifteen to what you want your theme to be called.

Now when we go to Appearances > Themes you should see as an option to activate. Go ahead and activate your theme! (If you get an error message, check to make sure you created index.php and functions.php and that neither of them have any spaces or extra content)

Awesome, you just activated your theme! Let’s go look at it by going to the frontend.

Annnndddddd White Screen! you scream – “Damnit Dan, what did you do!?!?!”

Don’t fret, nothing is broken. We may have a theme, but it’s not doing anything yet. Let’s go over to your index.php file and simply type “This will work”, save the file and refresh your site You should see the words you just typed, everything is working just fine!

For the rest of these posts, we will be mostly looking at the backend (the directories and theme files where your theme code lives) and setting up some basic structure on the frontend to display data. We are not going to be worried about styling for the most part, as that will be up to you once your theme is outputting the data you want.

Let’s get some data to work with

Because we don’t like wasting time, we are going to use the WordPress Theme Unit Testing Data XML file. This data is designed to test every capability and content type that comes baked in to WordPress, which is a good idea to account for in your theme.

Head over to http://wptest.io. and select “Download” to get your copy (you can also see the demo if you want a preview of what we are about to install). Once this is done, head over to Tools > Import in your local install and select “WordPress” (you may be prompted to install the WordPress Importer plugin – if so, please do).

You should now now be at a page where you can select the xml we just saved and import it. You can leave all the author options set as their defaults, but DO check the box to upload images.

Now lets go over to Posts and you should see a bunch of new posts that you just imported Note: For our sanity, find the post titled “Template: Sticky – Sticky” and set it to draft or put it in the trash for now (sticky posts have their own special rules when dealing with queries and it will get confusing when you are first learning – just trust me on this one).

This is where we’ll stop for now. In my next post we will add a few more template files and start looking at WP_Query to spit out some data on the front end.

If you’d like to have a look the theme files as they should appear now please head over to Github here and download them