Converting your HTML into a WordPress Theme:Part 2
In the last post, we covered everything surrounding our content (header, footer, sidebar) and got an intro to using WordPress functions in PHP.
Now, technically, the only other file you need is index.php. This is where you define how each blog entry is displayed. Again, using the index.php in WordPress’s default theme to guide us, this file contains:
- PHP comment with your theme name
- A PHP call to get_header() which says “insert the header (as we defined in header.php) here”
- <div id=”content”>, which contains our content:
- A PHP if/else loop that says
- IF we have_posts() to display, then display them (see The Loop below)
- ELSE display a Sorry, Not Found error message, optionally with a search form so people can try to find what they were looking for
- <div id=”navigation”>, which contains navigation links to move to previous & next pages
- A PHP if/else loop that says
- A PHP call to get_sidebar() which says “insert the sidebar (as we defined in sidebar.php) here”
- A PHP call to get_footer() which says “insert the footer (as we defined in footer.php) here”
If we find that we do indeed have_posts() to display, then we want to loop through those posts and display each one. This is done with an embedded PHP while loop that looks like:
<?php while (have_posts()) : the_post(); ?>
What this does is to loop through all of the blog posts to be displayed on the page. For each iteration of the loop, WordPress makes the next post’s data available so you can display it through a number of well-named WordPress methods like:
- the_title() – display the blog’s title
- the_content() – display the blog’s content (optionally with a Read More… as described in the docs)
- the_author() – the author
- the_time() – displays the date/time of the post
- the_category() – the category(ies) this post was filed under
- the_tags() – the tags assigned to this post
- the_permalink() – the URL to this post (e.g., you might make the post’s title a hyperlink to this)
- edit_post_link() – the URL to edit the post (will only display if the user has edit privileges)
As with other WordPress methods, you can often pass in arguments to customize the display to your liking – for example, the_time() allows you to specify the date/time format and the_content() allows you to specify the “Read More…” text. You’ll find a more complete list of available methods under WordPress’s Template Tags.
A few things to keep in mind:
- The loop includes logic to only display the posts appropriate to the page that’s been loaded. For example, if your blog is set to display 10 posts/page (via the admin console) then the loop will only loop through those 10 posts. Alternately, if you pull up the page for an individual post, the loop will only include that individual post.
- Many of the loop methods only work inside of the loop itself (because they’re pulling from the current post).
- If you retrieve information on other blog posts while inside of the loop, you may need to call wp_reset_query() to reset the loop back to the current post.
Individual Blog Post Pages (single.php)
Index.php is the default page that is used to display any blog listings on your blog, this includes:
- Your blog’s home page, which displays your most current blog posts
- Search result pages, where your blog displays any posts that matched the user’s search criteria
- Pages that list all posts for a given: date (e.g., 2009) or author or category or tag (you get the idea!)
- Individual blog posts – when you pull up the page for an individual post
This might be fine. Or, you might want to provide different layouts for each of these pages.
In particular, you’ll often want to define a different layout for individual blog posts. For example, you might only want to display comments on the individual page, as THC blog does. To do this, create a file called single.php in your theme. When WordPress sees that single.php exists, it will use that for individual (“single”) blog views in place of index.php.
The default theme comes with a single.php file. Notice that it follows the same overall format as index.php. That is, it includes the header, sidebar, and footer with the appropriate get_XXX() methods. And, it includes the loop. This might seem funny since single.php only displays a single post, but recall that the methods to get that post’s data are only available to us within the loop. You can rest assured though that the loop will only iterate a single time within single.php.
Use comments_template() to include comments within your page. You can further define how those comments are formatted in the files: comments.php and comments-popup.php, both of which are provided in the default theme.
The Hacker Chick Blog uses JS Kit’s Echo, a 3rd party tool for comments, and that handles the formatting itself, so I just copied the default comments.php into my theme but didn’t otherwise do anything with it.
Other index.php Alternatives
You can also provide different layouts for what people see when they get a search results listing (search.php), when they get a listing of posts by date (date.php), author (author.php), category (category.php) or tag (tag.php). You can even create custom layouts for a particular author, category, or tag. WordPress looks for files of a certain name (e.g., search.php or author-id.php) – if it finds it, it uses it, otherwise, it falls back on index.php.
Take a look at WordPress’s hierarchy for the complete list of options.
And with that, this hopefully gives you enough to start on your own custom WordPress design. I’d really love to see what people are doing – so please leave a comment with your URL and what you’ve done. Stay tuned and I’ll follow up with some extras like adding twitter feeds & related posts.
Are you customizing your own WordPress theme? Have any tips or tricks that you’ve found useful?
Photo credit: WordPress Eye Internetera.net