Wednesday, September 30, 2009

How To: Hack WordPress Theme Template Pages

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(); ?>">

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.

Perishable Press has a great tutorial for multiple loops, multiple columns – if you want to try and split your content up. They also have some great loop templates, in addition to a great tutorial of horizontally sequenced posts in two columns.


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!

Posted via web from sdn's posterous

No comments:

Post a Comment