Secrets of WP Themeing: The Complete Series

Tagged and

Here is my complete series on Themeing With WordPress 1.5 collected all in one place for your convenience.

Part 1: originally posted here

So lets talk about Custom Templates, and more importantly how we can bend them to our will. Now I am assuming that by now everyone has at least a passing familiarity with Templates in WP 1.5, for those who are not up-to-speed, lets cover some back-story.

In the beginning were Templates, and lo they were good.

Templates are the foundation of the WP theme system, and one of the most powerful features, in my opinion, in 1.5. A template defines the layout and “feel” of different aspects of your WP powered site.

There are a number of templates that are strictly defined in WP, they are as follows (list taken from the codex):

  1. style.css
  2. index.php
  3. comments.php
  4. comments-popup.php
  5. home.php
  6. single.php
  7. page.php
  8. category.php
  9. author.php
  10. date.php
  11. archive.php
  12. search.php
  13. 404.php

For instance, I have a template that defines the look of my index, one that defines viewing single posts and one for category listings. Each one has different structure, CSS and WP function calls based on its purpose. The one thing they all have in common is the_loop, or the bit of code that tells WP to spit out the appropriate posts for a specific area of my site.

So class, are we all caught up on templates? Good, well what happens when we want to add a page to our site that doesn’t have anything to do with our posts or categories?

Say we want to add an archives page like the one here at Sillyness to our sites?

Again we turn to Templates, more specifically Custom Templates.

Templates, Posts, Pages and Plugins

Now we have already stated that there are a number of strictly defined templates in WP. But there is also another category of templates, ones that can be anything, can be called anything and can be applied to any “Page” you create in WP. It is here with Custom Templates that the fun begins.

It is a little known fact that you can apply custom templates to blank “Pages” in WP. What I mean is that you can create a completely blank page in WordPress and then apply a custom theme laden with code to it. As an example lets look at the archives page here at Sillyness.

If you were to look at the page I created in WP named Silly Archives, the “Page Content” area would be completely blank. If you then opened my custom template you would see a whole mess o’ code, and interestingly enough the_loop is no where to be found. In fact the only WP core code that you would find would be get_header(); and get_footer();

The rest is either embedded code, or plugin calls.

So let’s get into some code.

So back to our hypothetical example. Our first step would be to create the custom template that will be applied to our Archives page. Because we do not re-invent the wheel, we will be making use of Shawn Grimes Clean Archives plugin, and my Commenter Heat Map plugin.

So first things first, every custom template must start with the following code:

In addition for this particular page we need to add a call to wp-blog-header.php so our opening code will actually look like this:

Next we call for our header.php file and start adding our content:

Here are the archives for .

Search the archives.

Now you could have put some of this in the “Page Content” area of the ‘Create Page’ screen, but for this demo we want to have everything in the template, so on we go.

Commenter Heat Map

Below is a heat map of the commenters here.

<?php cjd_comment_heat(); ?>

And finally we close with the footer call:

And that is the entire template, now we save it as new_archive.php and upload it to our /wp-content/themes/ourtheme/ folder, then log into our WP admin area to create a new Page.

Lastly we need to create a blank Page and link it up with our new template.

So let’s go to Write > Write Page and get to business. First off we need to give our page a title, let’s say My Archives, once that is done we can skip down past the “Page Content” area to “Page Options”.

The first field should be Page Template, and in the drop down box we should find Archives Template, select that and click Create New Page. That’s it, if you have installed and activated the plugins, when you load you should see your lovely new Archives page.

Well that’s it for the first of this series. I hope you have had as much fun as I have. If you have any questions, leave them here in the comments and I will do my best to answer them.

Part 2: originally posted here

When last we met we talked about Using custom templates to add pages to WP that don’t necessarily call for posts or categories, etc. Today we continue our exploration of custom templates by looking at another little known power hidden within the theme system: Per Category templates.

Hidden Spiffiness abounds

Deep within the recesses of the WordPress code base lies dormant the power to create custom templates for each of your categories, what is even more astounding is how easy it is to pull off. This sleeping giant merely awaits the correct file names and it will wake unleashing untold shininess and spiffiness upon your visitors heads!

It should be said that this isn’t a feature that we are all going to want to run out and use, but I think that for a select few this will be a a breath of fresh air, not to mention a solution to many frustrations.

When you get down to brass tacks, this is a profoundly easy feature to exploit. All you need to know is the number of each category and you know, what you want each one to look like. So lets look at how I am using this feature here on Sillyness.

Context sensitive information is the bees knees

I am a big believer in giving information to the user that is both contextually correct and also useful. A prime opportunity for this is when a reader is browsing your category pages.

Here on Sillyness where appropriate you will find in the left aligned column a list of “other resources” specific to the category you are browsing. Two prime examples are the Tutorial and Web Standards categories. On each one you will find links to offsite resources.

Now this is a very limited example of per category templates. If you wanted you could change every aspect of the way the page is displayed, load alternate style-sheets anything… the sky is the limit. But think before you go crazy people.

So what does one need to do to tap into the power of per category templates? Glad you asked!

So lets write some code, shall we?

After the previous discussion, creating these templates will be a piece of cake. First of all lets start off by making sure we actually have a category.php file to begin with. I find it very helpful to have a good layout with which to browse categories, and you readers will too.

So let’s say we are all brilliant and already have a category template file, we need to open that puppy up in an editor and decide what we want to customize for lets say… the gorilla category. Heh, gorillas are funny.

Okay so we are going to create a template for our gorillas category (cat number 18).. okay? Good. So I think we need to have some links to gorilla resources on the net offered to our visitors while they are in our gorilla category listing, don’t you?

So lets get to tinkering , first we throw out an oldy but a goody:

Next we call for our header.php file and start adding our context specific info:

Now usually we would want to just call <?php get_sidebar(); ?> and include the template file sidebar.php, but we are wanting to add that context info and the menu is the best place for it. So we will be hardcoding this bit on each template.

Then we go on and throw out the template tags that tell WordPress how we want to display our listing on the category page:

<?php the_excerpt(); ?>

<?php endwhile; else: ?>

<?php endif; ?>

And finally we close with the footer call:

Now for the payoff, making it all work

Okay, so now we have created a template for our gorilla category, complete with spiffy links about gorillas for our readers. Now we are ready to save this bad-boy, but how does WP know to use this when gorilla is called?

Now it is time to do something with that category number we found. All you need to do is save this file as category-n.php where n is the number of your category. So since gorilla is cat number 18 we would save this file as category-18.php and upload it to our wp-content/themes/mytheme/ directory.

Easy-peasy as they say. Believe it or not, that is all there is to it. The next time you load the gorilla category you should see the template we just created.

Well that’s it for this installment of the series. I hope you have had as much fun as I have. If you have any questions, leave them here in the comments and I will do my best to answer them.

Part 3: originally posted here

Well it is time again for everyones favorite series. So far we have covered some pretty groovy stuff. Part 1 showed us how to create custom code laden templates that can be applied to blank pages in WP to achieve some gnarly effects.

In Part 2 we talked about creating custom templates for each of your categories, opening up a whole world of possibilities. Today we are going to talk about a little used theme template, the Home Template (home.php).

There’s no place like Home

So as you remember we talked about the different files that WordPress is hard-coded to recognize. One of these that we have not talked about yet is home.php. This template file is only used when index.php is called without any arguments passed to it.

That is a mouthful, isn’t it? What that nonsense above means is the following. When you load this site, the physical URI, or address is, and when you click on a link to a specific post, say this one which is number 732, the address becomes index.php?p=732. Now p=732 is an argument, or rather how we tell WP that we want to see post #732.

My site uses some mod_rewrite magic so you dont see that, but trust me it is there, so home.php is only used when the physical address in the address bar of our browser is

And that matters to me WHY exactly?

Good question, glad you asked.

First, time for a little demonstration, take a moment and head on over to my test site and look around. Back now? Good. So what do we see over there? Well the top row contains images from my Flickr account, the second row features the latest 5 posts from The Test Bed and finally the last row contains the last 5 entries from my Support Forums. The index page has become more of an overview page, and you know the best part… I haven’t called the WordPress loop: <?php if (have_posts()) : while (have_posts()) : the_post(); ?> anywhere on that page.

Now what I am about to show you isn’t neccesarily the best way to go about this, I am merely choosing this course of action to demonstrate how powerful and completely disconnected from the core function of WP you can make home.php. Keep that in mind.

So how am I displaying all this info if I am not hitting the database for it?

Simple, I am using the WordPress version of magpieRSS to grab, parse and style various RSS feeds.
What home.php gives you is the ability to have a WP handled index page that can be more static in nature, with a blog behind the scenes. In essence we move closer to using WP as a Content Management System, as opposed to merely an elegant blogging platform.

Now of course you would want to have the_loop included in the home template to simplify matters, I just wanted to get across the extreme flexability of WP when using templates by going without it.

So lets write some code

Now for most of you this will probably be your first exposure to the RSS aggregation built into WP, don’t go nuts with it! It is powerful and easy to use, but you take a hit in performance when using it.

So we open up with the customary code:

Here is our first new bit, we need to call the rss functions and set a variable to todays date:

Recent Flickr

Now I am not parsing RSS for the Flickr area, since they (Flickr) provide a nice little solution for this already. I am not going to paste it all in here, but you can find the code easily enough if you are a Flickr user.

Okay here is where the fun begins, we are now ready to call and handle the first RSS feed.

items) && 0 != count($rss->items) ) {

So what have we done so far? We are telling WP that we want to grab the RSS feed from this site, and if the feed responds, then move on.

Latest Posts on

    items = array_slice($rss->items, 0, 5); foreach ($rss->items as $item ) { ?>

Okay the above snippet of code is saying, grab the pieces of the RSS feed, publishdate, author, title, content etc and create an array from them, and then for each of these arrays returned do what comes next.

  • '>
  • Okay, lets look at what is going on here. First we are grabbing the link for the item returned and passing it through one of WP’s many filters. This link will allow us to load the post in full at the site referenced. Since this is our own site, when you click on the link it will load the post using your single.php template.

    Next we grab the title that is returned, and then we close the link tag, moving on to grabing the pubdate - when the item was published, and then using human_time_diff we calculate how long it has been since the item has been posted. That gives us the groovy human readable 21 days ago stamp.

    For the forum section, we just follow the above steps, only changing the URI of the feed to Other than that everything is the same.

    After the second block of RSS aggregation code, we just need to add the closing code we need and we are done: