WordPress Theme Development – Template Order

Process is the key to efficiency. Building a good theme development workflow will shorten your project timelines and help keep you sane. But which template file should you start with? Should you jump into the blog list (index.php) first, or maybe the standard page template (page.php). How about the 404 error page… that one seems easy, right? Even though you can start anywhere, there is a logic behind the order in which you create and style your WordPress template files. Here is a look at my process.

According to the Codex the only files you really need for a theme are style.css and index.php. If only theme development could be so simple. More than likely your theme will consist of many more files than that. WordPress has a specific template hierarchy it uses to decide which template file to use for each page request. Each template files serves a specific purpose. You can also create template parts containing blocks of code you can reuse in multiple template files.

But this is getting us away from the point of this post. Once you have figured out which template files you  need to create you have to decide where to begin… and more important you should know why.

1. style.css

Start here. Every time. You have to setup your theme’s information at the top of the style.css file inside your theme folder so WordPress can see your theme and let you activate it. However, you do not have to use this file for your styles. Since switching to LESS I now create a sub-folder in my theme folder for all of my LESS files and a sibling folder with all of my rendered CSS (either by Grunt or CodeKit depending on the project). I also keep  LESS and CSS files from included libraries/frameworks like Bootstrap, Foundation, or FontAwesome in the same folders. I do my best to include as many style assets as possible in my primary style.less file so they all get combined and minified into one file that I load in my theme.

The same goes for Javascript — keep it in a separate folder, concatenate, and minify!

2. functions.php

Speaking of loading the stylesheet into my theme, this happens in the functions.php file (not in the header.php template file!). In fact, I always create an “includes” folder in my theme folder for additional PHP libraries/assets. These get included (or “required”) in the functions.php file. Some of these libraries are things that I have created that include common functions that I use to my my theme development easier. At the top I define several PHP constants that I will use throughout my code. Then I include additional libraries. Last comes all of the theme-specific functions. My goal for this file is to keep all common functions in the includes folder and only theme-specific functions/variables inside the functions.php file itself.

This is where you will register your menus and sidebars. This is also where you will enqueue all of your CSS and Javascript assets to be loaded in the header or footer. You can also include any hooks or actions here (such as creating a custom Gravatar default for comments or custom excerpt length with read more link).

3. header.php & footer.php

Now we get into actual front-end development work… finally! You should start at the top and the bottom. Figure out the common pieces you’ll need across all pages (like branding, social media links, navigation, footer widget areas, and copyright info.) and put them in their place in the HTML. Then decide what container you want around all of your page content sections. Open that container tag in the header.php file and close it in the footer.php file.

4. page.php

Next you might think you should start with the blog list (index.php or home.php) but I say no. Start with something a little more basic. Assuming that your pages and blog posts will look similar you should start with the page.php template because it has fewer elements overall (no tags, categories, or comments) but it does have  pieces that will carry over to the blog post template (title, content). Don’t forget to use a loop-page.php template part for extra credit!

5. sidebar.php

Before you wrap up page.php you will have to make sure your sidebar is setup and included properly. Now that Jetpack includes the “Widget Visibility” functionality sidebars are much easier to manage. We typically include a sidebar (or widget area) specific to blog pages and another one that is general for all pages. Sometimes I will setup the theme to use the standard sidebar if the blog sidebar has no widgets. You can call a blog-specific sidebar file in your blog template files by creating a sidebar-blog.php file and using the get_sidebar(‘blog’) function.

6. single.php

Before you create your list of blog posts (index.php) you should go ahead and make sure you have styles for your single blog post template. This includes title, date, author, content, featured image, tags, categories, and comments (at least). Again, extra credit for using a loop-single.php file!

7. index.php (or home.php)

Finally, your main blog list. This will often be a reduced version of the single.php file for each post on the page — sometimes with full content and other times with excerpts. Also make sure you check pagination. As an aside, I’m sure there are times when a home.php file is appropriate but I do not personally use them for anything.

8. archive.php & search.php

These files are cousins of the index.php file so most of your styles are already in place. Just make sure pages (and other custom post types) show up well in search results… you probably don’t need to show a date or author for pages.

9. 404.php

This is totally unique from the other templates we have been working with. It is essentially the page.php file with a search box and other appropriate information to help guide a visitor back to the right path on your website.

10. attachment.php

I generally use WordPress SEO to turn off the attachment view functionality but it’s always a good idea to include a template for it just in case.

11. everything else…

This is where things get very theme-specific. For example:

  • Are you creating custom page templates for this site? I generally provide one page template without a sidebar that is full-width. I also generally have a unique front page template (not front-page.php but a separate page template intended for the front page).
  • Do you need custom post types? If so, you will want some sort of list page, single page, and possibly term/taxonomy archive pages.
  • Are you using any plugins that allow you to create custom page templates like a calendar or store?
  • What about author bio pages?
  • Do you need custom templates for unique taxonomies?
  • What about custom RSS feed templates for podcasting or adding custom meta fields to your syndicated posts?

All of that is possible but all of it should all come last in your workflow.

And now it’s your turn! How do do things differently… and why? Do you have any other suggestions to keep your development workflow efficient and orderly?