Dissection of a WordPress theme: Part 4

Translation:

Resources:

In previous guides we have concentrated on the building blocks of a WordPress theme. A basic design structure has been defined, followed by enclosing header and footer elements, and finished off with a navigational panel. While important aspects of any blog, they are secondary to its main purpose: the content.

In this fourth and final part we carefully dissect the process of taking content from WordPress and arranging it on screen. Attention is paid to the alternative methods of grouping this information, from the multiple posts of the front page, to search results and archives.

We will look at how WordPress distributes responsibility for this work, and how everything is tied together with the all-seeing all-knowing construct known as ‘The Loop’.

By the end of this guide we should have a fully working theme and enough WordPress experience and knowledge to extend our theme beyond the basic design presented here.

The Loop

The Loop is the front-facing side of WordPress and sits at the top of the code hierarchy. Its basic role is to obtain information about posts that can then be displayed easily and conveniently.

It is called ‘The Loop’ because it is, very simply, a loop – there is no hidden trickery here. Each iteration through The Loop causes WordPress to load the post information, which is then accessed through special template functions. The Codex describes most of these functions in great detail.

The primary loop exists within index.php, but the loop can also be found in several other of the files contained within a theme. We will look at index.php in more detail shortly, but for now the loop can be extracted as a very short piece of PHP code:

while ( have_posts() ) : the_post();
  code
endwhile;

Yes, that really is it. All the underlying database work and the multitude of PHP files all boil down to whatever exists between these two lines. Breaking this down even further we have two WordPress function calls wrapped within a PHP while statement – PHP will execute whatever is between the colon and endwhile, so long as the condition is true.

In the above code, the condition is the first WordPress function:

have_posts ();

This is a simple function call that returns true if we have a post to display, or false if we don’t.

How does WordPress know whether we have a post to display? It deduces this from the URL of the current page. On the front page we may have several posts to display, while a single page will only have one. Regardless of the context, The Loop is fundamentally the same, and WordPress will stop the loop at the correct time by causing have_posts to return false when there are no more posts. Execution then resumes after the endwhile.

The second essential part of The Loop is:

the_post ();

You can think of this as being the function that tells WordPress to load the information for the next post and prepare it for our use. Each subsequent call of the_post will cause WordPress to give us the next post, and the next, and so on – it is basically a pointer that steps through the posts.

For example, if we have ten posts to display then have_posts will be called 11 times – the first ten will return true and the eleventh will return false. Each time it returns true, the_post will be called to get the information about the post.

Anything else following the_post and before the end of the loop is entirely our choosing, and is what we use to display the post information – it can be as basic or advanced as required.

Delegation of duty

WordPress provides many ways for us to display a collection of posts. For example, the front page contains the latest posts. The archive section will show a larger collection of posts, spread over a specific time period. The search page shows posts that meet search conditions.

Rather than having one super-sized piece of code that manages all of this, the work is broken down and delegated to several smaller handlers that deal with a specific task. Each of these will contain the exact same loop discussed above, but will process the information in different ways.

The handlers are spread across different files:

  • index.php – displays the front page
  • single.php – displays a single page
  • search.php – displays search results
  • archive.php – displays archives
  • page.php – displays a WordPress ‘page’

While this is very flexible, it does cause one problem: duplication. If we wish to maintain a consistent theme across our entire blog then we will need to duplicate it in each of these files. Fortunately most of the changes will be stylistic, and will only require a CSS modification. A basic structural change can cause a lot of work.

It should be noted that in previous guides we did in fact introduce a basic structural change. This means we need to update each of the files – an ideal reason to investigate everything.

105 comments

  1. Pingback: Colorado Contemplations - Journal
  5. Pingback: Dissection of a WordPress Theme: Part 4 by Blogging Pro

  8. Understanding WordPress Theme

    The final part 4 of what I can say a tutorial to understanding WordPress theme, Dissection of a WordPress theme has been posted to UrbanGiraffe.

    If you’ve been trying to create your own WordPress theme and don’t mind to take the time and learn it, …

    Reply
  9. Pingback: 小隆網管日誌 » Blog Archive » Dissection of a WordPress theme Part 4

  11. Thank you for the awesome Theme Guide series!!! I’ve been thinking about digging into Kubrick to find out how it worked, but I couldn’t figure out where to start, and it all seemed too complicated. Your guides made it seem a piece of cake. Really, I went through the first three “episodes” in only a couple of hours with excellent results. I even managed to make some modifications of my own: as my posts are usually really long, fixed width makes scrolling a painful experience, therefore taking advantage of the entire window width is mandatory. But I also wanted to keep a fixed width on the sidebar… A couple of wrappers, some negative margins and it worked! My blog will have a brand new theme in a couple of hours, as I complete the fourth tutorial. Thank you again!

    Reply

  12. Bye-bye Kubrick, hello Synaptic!

    WordPress 1.5 has a very powerful system to manage themes, but to the uninitiated with the inner workings of WordPress it seemed too difficult to take a bite at. Well, help came along in the form of UrbanGiraffe’s WordPress Theme Guide series of…

    Reply

  14. Thanks so much for this terrific guide! I’ve been learning CSS, and this guide will definitely help me ni creating my own themes. Before this, I didn’t really know where to start, but I followed your step-by-step directions, and it worked. It’s a great guide. Nice work!

    Reply

  17. John,

    It still isn’t working for me. It happens when I click on a short entry and it takes me to a single view of just that entry. There’s a big text box at the bottom of the page that says “Leave a reply” and the side bar kind of covers or gets covered up by it.

    I’m seeing it on:
    http://www.blendedtechnologies.com/thanks-for-looking/10

    Maybe send me your email and I’ll send you a screen shot.

    -Greg

    Reply

  19. I discovered this tutorial through BloggingPro and it’s restored my faith in Themes. Previously I was resistant to using Themes because they seemed so difficult to customise, but this was easy to learn and do. Thanks so much!

    I too seem to be having the comment box problem even when I’m logged out. I don’t think I did anything wrong, but I’ll go back and have a look when I have more energy. Once again, Thank You!

    Reply

  20. To fix the comment box problem you need to edit the comments.php file and remove the ‘cols’ value. You should then add a CSS style to make the width dynamic:

    #commentform textarea
    {
    width: 95%;
    }

    Reply

  24. It sounds like you need some spacing for your comment paragraphs. This is what I have on the current theme:

    .commentlist p
    {
    line-height: 1.4em;
    margin-bottom: 1em;
    }

    Reply

  26. John: Thank you for the fabulous tutorial. The default theme looks positively dreary to me, and not knowing how to customize it has kept me from using my blog at all. With your thorough instructions, I should be able to have something up and running soon.

    With MUCH appreciation,
    K.

    Reply
  27. Pingback: Grant Palin » Blog Archive » Useful WordPress Resources

  28. thank you very much for the tutorial. i never thought dissecting the default theme is that easy. I will design my own theme as soon as i get to download the Kubrick theme at my PC. If you know where to download it please email me (i don’t have a FTP client yet, so i can’t download the theme from the Fantastico). thanks!

    Reply

  30. Hi, I’d just like to thank you very much for this wonderful tutorial. It’s helped me out a lot. I’m still in the process of tweaking and making images for my site, but your help made it all extremely clear. Thanks!

    Reply

  31. I’d like to thank you as well for the guide. For anyone interested, I’ve done some of the legwork of the guide for you, and put together a blank theme of sorts, with the files stripped out, and a style sheet with all the divs and classes ready to be styled.
    More info can be found here

    Reply

  35. Hey, this series of guides saved my life. I wasn’t making sense of any of the other similar tutorials or the info in the Codex. This not only helped me make my “own” theme, but I think I may even understand how it works…! Thanks for doing this.

    Reply

  39. Hello John,
    I’m going to repeat what others have said: “Thank you very much” for this wonderful tutorial.

    Although I currently have no personal host, I’m trying to do this using my own webserver (Apache et all). Still have more to learn though, but your guide really is an excellent jump start.

    Thank you yet again.

    All the best!

    Reply

  40. hey john,

    your tutorials are great. really, someone should notice and get you to start writing some books that bridge the techie world with the not-so-tacky like us.

    – – –

    i’ve a question about this last section: i’ve followed your instructions to the T up to the part on single.php. and this is where i’m stuck. somehow i write the code, only to get a parse error:

    Parse error: syntax error, unexpected ';' in /www/n/needleplantc/blog/htdocs/wp-content/themes/MonkeyMagic/single.php on line 10

    i kept relooking the code you had on pg 4 of section 4, and tweaking the code, but don’t know what’s wrong. can you help? thanks so much.

    marko

    Reply

  41. Hi Marko,

    From the error message it looks like you have a typo in the code. It’s very easy to misplace a quote or semi-colon, so look at the code upto line 10 for an extra character that shouldn’t be there. Sometimes these mistakes are near impossible to spot, even after checking many times!

    Reply

  42. thanks for the rapid reply.

    i have another question: if i want to reduce the width of the leave a reply box to be more like yours (slightly shorter), how do i do this. i tried tweaking the comments styles for css sheet, but only managed to do other things.

    thanks

    Reply

  43. The are two ways of changing the comments box:

    <textarea cols='11' tabindex='4' rows='10' id='comment' name='comment'>
    </textarea>

    You can modify the cols attribute to change how many columns wide the box is.

    Alternatively, the CSS code is something like:

    #commentform textarea
    {
    width: 95%;
    }

    Reply

  45. Hey!
    Just wanted to join the ranks of those who found your wordpress deconstruction & reconstruction very helpful! I’m about to self-publish my first novel, and I wanted to let you know that your guide saved me a ton of work, and helped me to finish the book a months ahead of time. 🙂

    I did have one quick question though, because this has been bothering me for several years, and I haven’t yet been able to find a satisfactory solution. It’s like the problem of trying to eat spaghetti on a date *without* flipping sauce all over your pants: it never goes away.

    Anyway, if you take a look at my website (www.markeff.com) the front page acts just how I want it to. But if you go to the About page, the main content box occasionally rides the left edge of my sidebar, and I can’t for the life of me figure it out. I’ve scoured Google and Yahoo to try to find the solution to why that happens with my CSS, and to no avail.

    Reply

  46. Thanks Mark, and good luck with the book! Taking a look at your site I suspect that the problem may be caused by having a width for the ‘content’ area of 80%, but the sidebar is fixed at 155px. These should both be fixed widths

    Reply

  47. I customized my blog using your tutorial, and got exactly what I wanted, thank you so much for making this arduous process so digestible!

    Now to my question…
    I wanted my sidebar to be outside the content area, so I made the margin left slightly larger than the content area and then made the overflow visible, and everything looks great in safari and firefox and even IE on mac, but IE on windows looks horrible, the sidebar gets knocked down below the content, and the whole wrapper is nudged over 50 px or so.

    live here… http://blog.fearless-future.com/

    any ideas?

    Thank you!
    Jonathan

    Reply

  48. in the mean time, I have changed the overflow to hidden when the script detects IE, but obiusly this make the side bar completely useless in IE, so if anyone has any other real solutions, that would be great,

    Thank you!
    Jonathan

    Reply

  49. I’ve taken a quick look and it’s possible that Windows IE is displaying it correctly, and all the others are too forgiving! It certainly looks like one of those grey areas of CSS, and those are best to avoid. Generally this means changing your design for the sake of your sanity. Some things are just impossible to get working in every browser and you have to compromise eventually. The design is also not consistent in Opera (although it doesnt look too bad).

    I might have missed something obvious, but the only way I was able to get the sidebar to pop outside the wrapper area consistently was by setting it’s ‘position’ to ‘absolute’, and then setting a negative ‘right’ value. Provided you set the wrapper ‘position’ to ‘relative’ then the sidebar will jump outside the wrapper area anywhere you want it. However, this does cause other problems (to do with the height), and my gut feeling is to rejig the design so you dont go into the browser equivalent of the twilight zone.

    Hope that helps a little!

    Reply

  51. Hello John.

    First I would like to thank you for putting up this guide. It has helped me a lot in creating my own website, which can be found here: http://www.voiceofwarcraft.com

    The thing is, that while it looks good on Firefox, I am having trouble getting it to work properly on the Internet Explorer. For some reason, the homepage only shows two blog entries, where it should be showing more. This is also inconsistent, meaning that sometimes it shows all, sometimes it doesn’t.

    All in all my web design skills are fairly basic, and I would appreciate if you could have a look at the site and maybe help me out there.

    Thank you very much!

    Reply

  52. Hello John!
    Like so many others I found your tutorial very very useful!
    I seem to have the same kind of problem as Jonathan: in Firefox everything works fine but in IE my sidebar goes underneath the content and the content itself is shifted.
    I would greatly appreciate any suggestions!
    Thanks,
    Jenni

    http://www.readytorisk.org/

    Reply

  53. Ok nevermind, I fixed the problem using relative positioning. I think it was caused by the different way of interpreting margins in Firefox and IE (but I could be wrong).
    Thanks anyway.
    Jenni

    Reply

  55. I used your tutorial and I made the theme. It worked fine, but when i tried to apply this same tutorial to make theme of my own, I had some problems. It looks fine on mozilla firefox, but when I tried to open it in IE, the front page looks fine, but all the other pages are messed up. I’ve done everything I could but it just doesn’t work. I’ve checked and rechecked on w3c and my xhtml is valid. Please could you help me out. http://www.closure.nu/track

    Reply

  56. From what I can see, your sidebar is not inside the container on a single post. If you move the HTML for the sidebar in single.php inside the container then it should display correctly (why it displays ok in Firefox I don’t know!)

    Reply

  57. This tutorial was very helpful. I could tell from the start that WordPress could do what I wanted, but I just couldn’t figure out how. Thru your disscetion, I now understand what is going on and how to fix/take advantage. I picked up a printed copy as well. Hope you get most of the 12 bucks, it seemed the least I could do!

    Thanks again!
    john

    Reply

  58. This is great. I’ve copied what you’ve demonstrated and now I can’t wait to get started on my own design, now that I have some clue. There’s just one little thing. I’ve added the sidebar to the single.php as you suggested, but the Blogroll and Meta lists in the sidebar on the homepage don’t show up in the single page sidebar. Is this as it should be, or am I missing something? Either way, you’ve set a standard for documentation: concise, direct and thorough, that should be emulated across the Web.

    Reply

  59. Hi John,

    I want to thank you SO much for doing this! I tried in vain to understand the Codex, but then I found a link to this tutorial from the official WordPress site and can’t even believe I can understand this! I have a lot of experience in HTML, but not much at all in PHP. So I was afraid that I would be stuck with using themes other people made, even though I enjoy webdesign myself. I now have a wonderfully customized theme (albeit simple) to work off of. Now I just need to work on transfering my blog to it…but thank you again!

    Elisabth

    Reply

  60. Throughout my tweaked-using-this-tutorial wordpress site I’m getting validation errors on the page by using the following code as prescribed:

    The only “fix” I can deduce is to drop the – this makes page validate correctly but makes the footer hop into the bottom of the wrapper – is this undesirable aside from a design POV?

    many thanks for any help/opinions.

    Reply

  62. This tutorial was UNBELIEVABLE, it helped me go from WordPress-inept to finally understanding how to customize my own theme. Thank you so much!

    Reply

  63. thank you so very much for the wp theme guide! I really enjoyed it and it helped me along the way to finally create my own theme! Keep up!

    Reply

  64. Hi, u have a great guide to themes here. but i tried placing the sidebar on the left as opposed to the right and i changing the widths of the content so that if i changed bg color then it wouldn’t be affected. it worked. the problem is that it only works on one browser. when it works on firefox, IE won’t show them in parallel to each other and the sidebar falls to the bottom. if i adjust it for IE, then in firefox, the gap between the two is quite large. any ideas to fix it?

    Reply

  65. I’ve been running on my own home-brewed blogging system for over five years now and I’m going to be making the switch to wordpress. The two things standing in my way are 1) transfering over my design and 2) importing all of the old entries.

    Thanks to this fantastic tutorial, I saved a lot of time pouring over those files myself to see how it worked. Thanks!

    Reply

  66. Hey,
    Great tutorial! I like the fact that it doesn’t only tells you what to do, but also why.
    But there was one problem I ran in to: I put the sidebar on the left side and when I clicked on a post, the content was floating on the right side what made the page look really ugly. I solved this problem by not floating the div “content” on the right side, but the class “narrowcolumn”.
    Maybe you should notice that in the tutorial 😉

    -Eva

    Reply

  67. Hi,

    Brilliant tutorial. Easy to follow and great for learning how CSS works. One question though, I am stuck on changing the colour scheme of certain elements such as ‘blockquote’ and ‘meta data’. I can’t seem to change the background colour around my text *without* changing the whole websites text background colour. See this image for an example:

    http://www.geocities.com/not_me_guv/misc/metadata.jpg

    Anyone know what i am missing?

    Thanks

    Jimbob

    Reply
  69. Pingback: Standing Tall » Blog Archive » WordPress テーマの詳説：第四章

  70. Hi Great tutorial … really helped, as this is the first time I’ve really looked at WordPress…

    The one thing I can’t get my head around is comments.php

    The whole theme (www.shellyradley.com) works until you try to add a comment.
    Then that middle section moves to the left and is out of synch …i’m trying to get it to stay in the content area, and still have the sidebar on the right…

    I don’t seem to be getting anywhere by adding like we did on the other pages..

    I’m sure its a simple part I have overlooked! .. any ideas ?

    thanks

    Reply

  79. What can I say but thanks!
    I spent more time searching for a howto simple and detailed as this one is than it took me to go through the first part of it. It makes one think.

    It is really great in any way. However, I miss couple of things like two sidebars in the layout and some other details. I suppose that is my homework for this night. 🙂

    Reply
  80. Pingback: Create a wordpress theme from scratch « Fighting with CSS questions - a way from newbie to master CSS

  82. Thank you very much for your tutorials! I used your tutorial along with another and I got exactly what I wanted. Before I had a faulty template that worked fine in IE but horribly in FF. I ignored it for a long time, because I was too tired to fix that. However, today I decided to go for it and made the template again. I don’t know PHP and I’m not great with coding in WP, but using your tutorial made it much easier. Thanks!

    Reply

  83. Thanks for making this guide! I’ve been trying to learn the basics of themes for awhile now and your guide has done the trick. I now feel that I have an idea of what is going on under the hood.

    Reply

  86. Hi…

    John, thanks alot for your article. I used theme &gt;<a href="" rel="nofollow">

    I've changed code above with kubrick navigational code to replace the Older Entries and Newer Entries text with post/article title. Like below :

    <code></code>

    I got above code in kubrick's single.php file. But the output is disappear. I've read the tut on http://codex.wordpress.org/Template_Tags/posts_nav_link and implemented some guidance on that but still can't change the older Entries and Newer Entries text to post/archive title.

    So, please tell me the way. Thanks</a>

    Reply
  87. Pingback: Kubrick and K2 WordPress Themes: Collection of Theme Tips « Lorelle on WordPress

  89. I do not want a date or time to appear below any of my posts (I’m using WordPress as my CMS). What must I delete and/or modify, and on which pages? Thanks for a useful and well-written guide.

    Reply

  90. Patrick, the time and date is typically displayed with something like this:

    <?php the_time('l, F jS, Y') ?> at <?php the_time() ?>

    Just delete this from your theme.

    Reply

  91. Hi, John,

    I am exploring the possibility of using WordPress 2.5 for my site and was delighted to discover your 4-part article. The article clarified my understanding of WordPress theme design enormously. Thanks!

    About the only problem I had with my first read and implementation on my Apache testbed was the references to the .entrytext class. This has apparently been changed to .entry in the latest version (for example, in the code for the single.php file show below). Changing .entrytext to .entry where it occured made everything come out alright.

    (page 4 part 4)
    .entrytext .postmetadata
    {
    font-size: 1.1em;
    background-color: #FDE5C3;
    width: 70%;
    margin: 2em auto3.5em auto;
    border: 1px dotted #e9b17b;
    padding: 5px;
    padding-left: 45px;
    background: #FDE5C3 url(images/metadata.png) no-repeat scroll top left;
    }

    Again, thanks for the great articles.

    Royce

    Reply
  92. Pingback: WordPress Developer’s Toolbox | Developer's Toolbox | Smashing Magazine
  93. Pingback: WP开发者资源-2.1: WordPress主题制作基础教程 | 帕兰映像
  94. Pingback: » How To Develop Custom WordPress Themes! Candid Software Weblog -Web Designing, hosting, ecommerce, content and more!
  97. Pingback: android4us » Blog Archive » WordPress 开发者工具箱（上）
  98. Pingback: WordPress 开发者工具箱(1) | 窝棚-WPCMS
  99. Pingback: 逐浪·网络 » Blog Archive » WordPress 开发者工具箱
  100. Pingback: - WordPress 开发者工具箱（上）【联讯网】

Leave a comment

Your email address will not be published. Required fields are marked *