The key to being able to display exactly what you want in WordPress is understanding WordPress theme template pages. These are the theme files that display pages, not the ones that perform functions like comments, sidebar, etc. Most of us don’t use the WordPress default theme that comes with installation, and end up downloading a free theme from the Internet. This is a great way to customize your blog, but not all theme authors code their theme the same way. The capabilities of that theme largely depend on how much time the web designer took to code it, in addition to their knowledge of WordPress itself.

I’m going to explain everything you need to know to be able to customize all your theme pages any way you want, and this will give you enough information to begin coding your own theme as well. Even if you’re an ‘expert’ theme coder, you should learn something new from this article.

How WordPress Works

The most important thing you could learn about WordPress is the Template Hierarchy, or – “the order in which WordPress calls pages”. The ONLY file that is required in the PHP files of any WordPress theme is the “index.php”. That’s it! That one file could handle every single function WordPress performs (if you wanted it to). Or, you could have a WordPress theme that had a PHP theme for for every single WP function (or anything in between).

The Order of Things

Every time a WordPress page is called the WP ‘engine’, if you will, determines (through process of elimination) what kind of page it is. It’s kind of like a “where am I?” function. WordPress says “what page am I…” and in turn tries to call pages in a specific order. If WP doesn’t find the PHP file it needs it just defaults to the “index.php” file and uses it instead. There are 9 basic kinds of pages WordPress looks for first:

Am I the Home Page?
If WP thinks it’s on the home page it will look for “home.php” first, and “index.php” second.

Am I Post Page?
(Single) post pages look for “single.php” first, and then default to “index.php”.

Am I a ‘Paged’ Page?
(Static) or ‘paged’ pages in WordPress look for a “pagetemplate.php” first (if assigned when published), “page.php” second, and default to “index.php” last.

Am I a Category Page?
When WordPress determines it’s on a category page first it looks like a category specific ID page, such as “category-7.php”. If it doesn’t find that it next looks for a “category.php” (which would be used on every category page). If that’s not there is searches for “archive.php”, and last it defaults to “index.php”.

Am I a Tag Page?
If WordPress is on a tag page it tries to load “tag-slug.php” first, with ‘slug’ being the name of your tag. If your tag is ‘wordpress hacks’ the tag slug page would be “tag-wordpress-hacks.php”. It that’s not available, WP next looks for “tag.php” which would load for all tag pages, then “archive.php”, and if that’s not there last it defaults to “index.php”.

Am I an Author Page?
If your blog has multiple authors, first it looks for “author.php” to display the details. If that’s not there, it tries to load “archive.php”, and last it defaults to “index.php”.

Am I an Archive Page?
Archive pages are loaded when WordPress loads a date based page for previous posts. First it tries to load “date.php”, then “archive.php”, and last it defaults to “index.php”.

Am I a Search or 404 Page?
If WP determines it’s on a search (results) or 404 (not found) page the it tries to load either search.php or 404.php. If not, the default is once again “index.php”.

Am I an Attachment?
Out of all the WordPress theme template pages, the attachment page is probably the one used least, and I have to admit – I’ve not seen a single one of these in any of the hundreds of themes I’ve downloaded. WordPress uses these special pages usually for uploaded content, which would explain why it first looks for “image.php”, “audio.php”, “video.php”, or “application.php”. Then it tries to find “attachment.php” or “single.php”, and if none of those are available it also defaults to “index.php”.

Inner Workings of WP Theme Templates

As I said before, you could use a single index.php file to handle the 9 types of pages. You would simply code in some conditional tags, like I showed you in the last tutorial I wrote here on WP Hacks. A single index.php would then just contain code to say if is_home, do this, if is_single do that, etc. That’s a lot of code for just one page, and a bit unorganized – and it doesn’t leave a lot of room for customization.

Coincidentally, like WordPress searches for 9 basic pages – each theme template page also contains 9 basic WordPress elements:

  1. a header call
  2. opening of ‘the loop’
  3. a call to get the permalink and (some) meta
  4. a call telling WordPress what to get
  5. a call to get either the content or an excerpt
  6. (maybe) more meta
  7. closing of ‘the loop’
  8. a sidebar call
  9. a footer call

Those are only the WordPress elements, of course the PHP code to make them work is usually scattered throughout the appropriate HTML code make your theme’s layout and graphic design work properly. I’m going to explain these elements a bit more so you can understand how you can customize (or create) nearly any theme template page.

Header, Sidebar, and Footer calls

I’m going to handle all 3 of these elements at once, since they are all basically the same. When you see this code in a template:

<?php get_header(); ?>

WordPress is simply opening the “header.php” file. The same is true for get_sidebar (sidebar.php) and get_footer (footer.php). You could have multiple headers, footers, or sidebars, see the earlier link above for conditional tags.

Opening of “the loop”

The infamous “WordPress Loop” is when a call goes out to the database to do something until WordPress says “stop”, i.e. ‘get me the most recent full text posts in their entirety’. The structure of ‘the loop’ changes depending on what kind of page your displaying, and each of the 9 basic types of pages WordPress tries to load has a ‘loop’.

The opening of the loop generally looks like this:

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>

You may see it broken down with have_posts on one line to define conditional tags with the while and the_post on another, but it’s still the opening of the loop, and it’s pretty much the same in all pages. One way to use the multi-line loop opending is to place a parameter between “if have_posts” and the rest by using query_posts in between to show only a single post, posts from a time period, the last post only, posts from certain categories, or even change the ordering of posts being iterated in the loop.

A Call to Get the Permalink and (some) meta
The very last section of the loop opening (the_post) actually makes individual data available through each iteration of the loop. This data referred to usually as “post meta” because it’s descriptors and identifiers for the individual content being looped through. Typically things like the permalink (URL), title, date, etc. I say ‘some’ meta, because most themes show some things before the individual post content, and then some after – such as categories and tags.

Here’s a short list of things you can call in post meta: the_permalink, the_ID, the_title, the_time, the_author, the_author_email, the_author_posts_link, the_category, single_cat_title, the_tags, single_tag_titls, edit_post_link, comments_popup_link, comments_rss_link

Example code you might see for post meta would be something like this:

<div class="post" id="post-<?php the_ID(); ?>">
<h2><a href="<?php the_permalink() ?>" rel="bookmark"><?php the_title(); ?></a></h2>

A Call Telling WP What to Get
Next WordPress will decide how much of the actual individual post content to get for you. How much is gathered from the database depends on whether your look uses “the_content” (to get it all) or “the_excerpt” (to get part of it).

(Maybe) more meta
As I previously mentioned, the common things to see after a post are assigned categories or tags, and sometimes you see an “edit” link here as well. Some themes even put date published meta after the post content.

Closing of ‘the loop’

The code looks like this:

<?php else : ?>
<?php endif; ?>

Typically it’s on more than one line in case you want to build an option in, such as a message “Sorry, we didn’t find anything”. After the sidebar, before the sidebar and footer calls, is where you typically find the “next” and “previous” navigation links.

Bastardized Loops?

Well, just because most loops look like the examples I just gave you, doesn’t mean you can’t bastardize them in just about any way you can imagine. I recommend you read the WP Codex page The Loop in Action for examples of archive, category, and single post formats – as well as static home page.

The Codex official page for the loop has several examples of how to place multiple loops in one page.


Armed with just a tiny bit of knowledge, you can hack just about any WordPress theme template page to do just about whatever you want! Now that you understand (in great detail) how WordPress calls it’s pages and how the loop works, you can conquer any task! Have fun customizing your blog’s theme!

Kyle Eslick is WordPress enthusiast who took his passion for WordPress to the next level in 2007 by launching as a place to share hacks, tutorials, etc. Follow Kyle on Twitter @KyleEslick!

  1. Randy Hoyt says:

    Good article on template hierarchy. The only suggestion I would make would be to change your first question from “Am I the Home Page?” to something like “Am I the main Posts page?” It’s possible in WordPress (Settings > Reading) to set up a static page as the home page and another page to display the list of blog posts that normally goes on the home page. In that case, the posts page still uses [home.php] even though it’s not the home page; the home page will then follow the path for regular pages.

    • Renz says:

      That’s a good point Randy. This article is really helpful for my friend because, he’ll be developing his own templates soon.

  2. George Serradinho says:

    Wow, these are great tips. It helps to know there is a place where you can come and get these tips.

    I’m trying my best to understand WP more and you just nailed what I was looking for the other day.

  3. Gagan says:

    Very useful tutorial that helped me a lot to understand WordPress more.

  4. Ben says:

    Thanks for that.

    Very clear explanation of the WordPress platform from the pages point of view. Although I understand WordPress now I would have liked something like this when I first started out online.


  5. Jeff Houdyschell says:

    Nice post but…
    Its never that easy to hack a WP theme. WP Themes are all coded so differently that its just too hard to try to explain how to edit one…Good luck trying to explain it and have fun trying to answer all the questions you will get on this…

  6. Jeff Starr says:

    Excellent article, and a great explanation of template hierarchy and how it applies to theme template files. I will be referring my clients to this page when explaining how their new themes operate. Thank you!

  7. Quality SEO Services says:

    Just like the user before me mentioned, there’s no such a thing as hacking into your email account using nothing more than your email address. Unless it’s an inside job. Whatever you are using for blog.

  8. Suzanne says:

    Thanks … Not sure I still understand the loop thing … lol
    But you gave me enough links to check it out

  9. Used atvs says:

    Very informative article on “Template Hierarchy”…

    sme of thn r really gr8 tips.. Basically it makes u understand wordpress mre..

    Have heard dat its nt easy to hack wordpress theme..bcz thy r coded very diffrently and hard to solve it..

    Bt dis has clear my doubts..

    Thnx 4 sharing:)

  10. Sara says:

    Thank you for this post! I’m just starting with WP and this is SO useful!

  11. Greg Lam says:

    Thanks for the info on what wordpress does when looking for template files for attachments. I had created a custom attachment.php page and couldn’t figure out why it wasn’t using it. It is only when I read your post that I realized that wordpress looks to image.php first.


  12. jens says:

    still not understand why people want to hack wp theme

  13. vec says:

    Hello everyone,

    I need your help, I want to put a banner above the wordpress post editor and I do not how to do it. If you have any idea.. It would be a great help.. here’s the screenshot.

Trackbacks/Pingbacks »

  1. Wordpress How To Articles - May 24, 2009 says:
  2. Details on the 10 Most Helpful Wordpress Design Blogs | Arbenting says:
  3. WordPress Weekend Resources - May 22, 2009 | says:
  4. Wordpress ile ilgili takip edilesi 10 muhte?em blog | Blog, Design, dizayn, Kaynaklar, kodlama, web design, Web Dizayn, WordPress, wordpress kodlama, wordpress tasar?m says:
  5. Wordpress ile ilgili takip edilesi 10 muhte?em blog | MSN Sözleri | Güzel Sözleri | Özlü Sözler | Sevgi Sözler | Diziler | Filmler | Oyunlar | Yava? | Sa?l?k | Sanat | Spor | Haber says:
  6. Wordpress ile ilgili takip edilesi 10 muhte?em blog « Bay Bedava – Netten Ba?l?klar says:
  7. OneAnother » This new OneAnother site says:
  8. 10 Most Helpful WordPress Design Blogs | Cosmos Blog -- Internet News,Life,Culture,Polices,Resource,Make Money says:

Tweetbacks »