Here’s a quick reference to the filenames WordPress looks for when it renders each type of page.

When you’re using a child theme, the template hierarchy becomes a little more complex. WordPress will first look for the most specific template in your child theme, then to the parent, then back to the child for the next most specific, then back to the parent again—all the way down the line until it finally falls back on the parent’s index.php file. Is your head spinning yet? Here’s an example.

Let’s say you have an FAQ page with a slug of faq and an ID of 12. WordPress will first check whether you’ve specified a template in the page’s settings; if not, it checks for the following files in order:

Of course, WordPress can do all this in the blink of an eye.

As we learned back in Chapter 4, Thematic is a great framework because it’s packed with cool functionality. To best understand how to build on its templates, we should spend some time finding out how they’re put together.

Let’s take a look again inside Thematic’s directory; you’ll see a pile of template files, and if you were paying close attention to the previous section, many of these should be familiar to you:

There’s also a curious-looking directory, library, which is filled with directories for styles, languages, scripts, and so on. The most interesting subdirectory in there is extensions—it contains all the stuff that makes Thematic do the voodoo that it do. Erm, does. Here’s what’s inside:

The names of each of these files should give you a clue as to what they deal with: footer-extensions.php obviously relates to footers, comments-extensions.php to comments, and so on.

When you’re working with a theme framework, the simple way to build your own theme template is to copy the relevant file from the parent and place it into your child theme. As we’ve just seen, when WordPress is rendering a page, it will check the child theme first, so any template we put in our child theme will override the equivalent template in Thematic. For our first trick, we want to remove the sidebar from the home page. When WordPress wants to render the home page, it will first check the settings to see whether the blog administrator has specified a page to act as the home page; otherwise, it will look for the home.php template.

Thematic lacks a home.php file to copy, but index.php will suit our purposes nicely as it currently includes all the page elements we want, as well as a list of recent posts. Copy it from Thematic, place it into your child theme, and rename it to home.php. Here’s the new template in its entirety:

<?php

  // calling the header.php
  get_header();

  // action hook for placing content above #container
  thematic_abovecontainer();

?>

    <div id="container">
      
        <?php thematic_abovecontent(); ?>
     
        <div id="content">

          <?php 

      // create the navigation above the content
      thematic_navigation_above();

      // calling the widget area 'index-top'
      get_sidebar('index-top'),

      // action hook for placing content above the index loop
      thematic_above_indexloop();

      // action hook creating the index loop
      thematic_indexloop();

      // action hook for placing content below the index loop
      thematic_below_indexloop();

      // calling the widget area 'index-bottom'
      get_sidebar('index-bottom'),

      // create the navigation below the content
      thematic_navigation_below();

      ?>

        </div><!-- #content -->
      
        <?php thematic_belowcontent(); ?>
    
    </div><!-- #container -->

<?php 

  // action hook for placing content below #container
  thematic_belowcontainer();

  // calling the standard sidebar 
  thematic_sidebar();

  // calling footer.php
  get_footer();

?>

Were you expecting a bunch of HTML, curly braces, and a mess of if statements? All we have here is a couple of lonely div elements, and a whole lot of PHP function calls.

The reason for this is that Thematic templates are extremely modular—that extensions folder we noticed earlier is where much of the real action takes place. We’ll delve deeper into what all these functions do and how to make sense of this sort of template later in the chapter. For now, let’s focus on accomplishing our first task.

Looking at our freshly copied template, it’s easy to see where the sidebar is coming from:

// calling the standard sidebar 
thematic_sidebar();

Removing it, of course, will be as simple as removing the call to the thematic_sidebar: feel free to remove or comment out^[4] those two lines.

Since we’d like the content to now span the width of the entire page, we’ll need to modify the CSS applied to the main content column. We’re importing Thematic’s style sheets in our example, so there are two selectors that apply to the two divs: #container and #content, each specifying a width. We also learned back in Chapter 4 that Thematic loads up a bunch of classes on the body element, one of which we know will tell us we’re on the home page.

You CSS whizzes have surely already figured this one out: we can alter the CSS in our child theme so that #container and #content have a greater width when they descend from a body with a class of home. To do that, simply insert the following styles into your style.css file:

/* =Homepage specific styles 
-------------------------------------------------------------- */
body.home #container { 
  float: none;
  margin: 0;
  width: 960px;
} 
body.home #content {
  width: 900px; 
  overflow: hidden;
  margin: 0 0 0 10px;
}
body.home .hentry {
  width: inherit;
}

…

Now, open your browser and take a look at your site’s home page—you should find that the content occupies the entire width of the page, with nary a hint of a sidebar. And, if you navigate to any other page, you will see the sidebar reappear and the main content column take on its previous proportions.

Quite simple, right? But what we’ve just discovered is important: we’ve seen how easy it is to switch off an entire Thematic area without touching a single part of the parent theme’s templates.

The next step in our custom home page layout is to modify the footer so that it includes a list of the blog’s top-level pages. We now know that get_footer will look for a file called footer.php and include it. But if you call it with an argument, as in get_footer('homepage'), it will instead pull in footer-homepage.php. Near the bottom of home.php, you’ll see where home.php calls on get_footer:

// calling footer.php
get_footer();

To call on another file instead, give it an argument:

// calling footer.php
get_footer('homepage');

Of course, this will do very little for us at the moment—we’ll need to create footer-homepage.php. Again, copying from the parent theme is a great idea. We’ll copy footer.php from Thematic, and place it into our child theme, renaming it footer-homepage.php. It looks like this:

  </div><!-- #main -->

  <?php

  // action hook for placing content above the footer
  thematic_abovefooter();

  ?>    

    <div id="footer">

    <?php

    // action hook creating the footer 
    thematic_footer();

    ?>

    </div><!-- #footer -->

  <?php

  // action hook for placing content below the footer
  thematic_belowfooter();
    
  if (apply_filters('thematic_close_wrapper', true)) {
    echo '</div><!-- #wrapper .hfeed -->';
  }

<?php 

// calling WordPress's footer action hook
wp_footer();

// action hook for placing content before closing the BODY tag
thematic_after(); 

?>

</body>
</html>

Around line 13, thematic_footer appears: this controls the display of the footer text, which you can set in the options panel Thematic provides to the WordPress admin section. We’ll learn more about custom options panels and how you can create one for your child theme in Chapter 7.

Now, to put the list of pages in: WordPress’s wp_list_pages function will do exactly that. Most times when you find yourself wanting to include some additional content in your theme, WordPress will have a function ready to provide the information you need. Just have a look around the Codex: most functions have names that give a clear idea of what they do.

We could plop wp_list_pages right there in our new home page footer template, and it’d all work fine. But as a point of good housekeeping, it’s a better idea to stash this away in our functions.php file. functions.php tends to serve as a catch-all for the custom functionality you add to your child theme. By storing our page list generator in there, we ensure that if we ever need to call on it in some other part of our template, we can find it easily and refer to it in a simple fashion. Pop open that functions.php file and write your first custom function:

<?php
function wicked_footer_pagelinks() {
  echo '<ul id="simplepages">';
  wp_list_pages('depth=1&sort_column=menu_order&title_li='),
  echo '</ul>';
}
?>

It’s fairly straightforward: we’re using PHP’s echo function to spit out a ul element wrapping the list of pages, with an id so we can target it easily in our CSS. The only tricky part is the argument string passed to wp_list_pages.

As always, the ultimate reference for understanding how to use a WordPress function is the Codex, but I’ll break down the arguments I’m using here. depth specifies how far WordPress should dig into the site’s page hierarchy. By specifying 1, we’re telling WordPress that we only want top-level pages. sort_column specifies how the pages should be sorted. There are a number of different options that can be provided here: you can sort by ID, name, author, date modified, and so on. menu_order is the way the pages are ordered by the user in the admin section, so it’s a sensible choice. title_li is used to set a title that will appear at the top of the list. By passing in '' (an empty string), we’re telling WordPress to omit the title, and also not to wrap the pages in a ul (since we’re providing that ourselves).

Again, all these parameters (and several others) are described on the Codex page for the wp_list_pages, so you should have a read through that, or the page of any WordPress function you plan on using.

Now that we’ve created our function in functions.php, back in our footer we can call on the function like so:

<div id="footer">
  <?php
    wicked_footer_pagelinks();
    // action hook creating the footer 
    thematic_footer();
  ?>
</div><!-- #footer -->

Save all your changes, jump into your browser, and head on over to your child theme’s home page. If all went well, your list of pages will be waiting for you at the bottom. Now all you need to do is add some CSS to make them pretty, and you’re ready to rumble! Here are some starter styles that display the items horizontally and lose those pesky bullet points:

body.home ul#simplepages {
  width: 940px;
  margin: 0 auto;
}

body.home ul#simplepages li {
  list-style-type: none;
  display: inline;
  margin-right: 30px;
}

What we’ve learned here is how to insert some new content using WordPress’s template tags, and how to take advantage of WordPress’s custom template includes. That’s great, but there’s one more big piece of the WordPress and Thematic puzzle that you’ll need to master: hooks and filters.

Let’s have a look at one simple example of how you can use a hook to modify your theme. Favicons are those little icons you see in the tabs, titles, bookmarks, and history areas of your browser. Why not add one to your theme? And while you’re at it, you might like to add a larger icon for iPhones, iPads, and iPod touches.

First, create your favicon—there are plenty of online resources to help you out. Call your icon favicon.ico, and upload it to your theme’s directory.

Next, in functions.php, we’ll make a simple function that constructs a link to the location of the favicon. The URL of your theme’s files is provided by WordPress’s get_bloginfo function, and we’ll specify the rest of the URL ourselves:

function wicked_favicon() {
  echo '<link rel="shortcut icon" href="' 
      . get_bloginfo('stylesheet_directory') 
      . '/images/favicon.ico"/>';
}

Note that in the above code, we’ve assumed that your favicon will live in a directory called images—if you put them elsewhere, be sure to say so in your function.

Now, we need to add the action to the theme’s head. Fortunately WordPress has an action hook that’s triggered when the head element is being constructed: it’s called wp_head. So, following the format we saw above for using add_action, all we need to write is:

add_action('wp_head', 'wicked_favicon'),

Because the order of links in the head is of no consequence to us, there’s no need to worry about specifying a priority; our wicked_favicon function accepts no arguments, so it’s unnecessary to specify $accepted_args either. That leaves us with just the action we want to hook into, and the function we want to attach.

The same technique works for including extra style sheets or JavaScript files—anything that ought to go in the head can be added to wp_head.

Of course, adding markup to your theme’s head element is fairly uninteresting: most times you’ll want to be playing with markup inside the site’s body. Fortunately, Thematic provides a number of its own hooks, which we can use to add, remove, or adjust code at varying points throughout any page. Most of them are named according to where they are in the template, or what they do; here are the hooks you’ll find most useful as a themer:

If you’re the more visual type, check out this nifty wireframe by ThemeShaper Forums member dwenaus. It shows every widget area, major chunks of markup, and the most useful hooks as they appear in a template.

Unless you have a much better memory than me, though, you’ll probably never remember every hook and function available to you, so there’s no sense in trying to learn them. Instead, you should focus on learning the process of finding what you want. Dig into the templates and Thematic’s extension files, and consult the WordPress Codex when you run into functions that are part of WordPress’s core functionality. To give you an idea of how that’s done, let’s tackle an example from top to bottom.

That was a lot of information, and we’re yet to do very much actual template hacking! Rest assured, it’s all important: the more you understand the WordPress theming engine, the better equipped you are to make some seriously wicked themes. As you become acquainted with WordPress and Thematic, you’ll find that a good understanding of all these bits and pieces will make it easier for you to make precision changes to existing templates, or even build all-new ones.

For now, though, it’s probably time to grab a snack or tasty beverage. When you return, we’ll start putting that big, fat stack of knowledge to good use.

All of the modifications we’ve made so far have relied on action hooks. Let’s try one with a filter hook, shall we? Unlike an action, a filter will receive some content from WordPress that it can modify and must then pass along, so that lower priority filters can act on it, and so that it can be output. This means that your filter function should accept an argument (the initial content), and needs to return the modified content (the output) when it’s done.

For this example, we’ll be adding a social media share button to the end of every post. We’ll grab a nifty combined share button from AddThis, though you could use whatever share buttons or combination of them you prefer. Head on over to AddThis.com and grab yourself a button (choose Website from Select your service, as the WordPress option provides you with a plugin rather than a code snippet). At the end of the process, you’ll be given some HTML to copy and paste into your template. We’ll use that in our function:

function wicked_linklove($content) {
  if(is_single()) {
    $content .= '<div class="linklove">
      Did you love this post? Tell everyone you know, right now!
      … Paste the markup you received from AddThis here.
    </div>';
  }
  return $content;
}

Notice that, unlike the action hook functions we wrote previously, this one accepts an argument: $content. That parameter will contain whatever content WordPress is applying a filter to. We take that variable and append our new .linklove div to it, then return it for subsequent filters or for display (if our filter was the last one).

We’re also using a quick if statement to check if the post is being displayed on its own page: we only want to display the share link on the full view, not in excerpts. This is accomplished with WordPress’s is_page function. WordPress has a great selection of these conditional tags that allow you to display content based on the conditions met by the current page; it’s worth becoming familiar with them.

Now to tell WordPress to apply this filter to each post’s content. Thematic passes the full content of every post through a filter handily named thematic_post, so let’s try using that:

add_filter('thematic_post','wicked_linklove', 90);

We have used a priority of 90 to try to ensure that our filter will execute after any other filters modifying the same content; the priority argument is entirely relative to the other filters, so if it appears in the wrong place just try adjusting the number up or down. Load it up in your browser: instant social media rockstardom is yours!

Many blogs often include a small biography of the author/s at the bottom of a post. Here’s how to add a bio box to the end of your posts. We’ll be using the same thematic_post filter that we used above.

First, let’s write our function—the pattern should be growing familiar to you by now! The first if statement checks to see if we’re in a single post or a page (as we only want to display the author bio on the full view, and not in lists of posts). Assuming either of these conditions is true, our function then builds a div, a heading for the author’s name, the author’s Gravatar at a size of 50 pixels, and the bio from the author’s WordPress profile. We then return the post content with the new div attached. Here’s our function:

function wicked_showbio($content)  {  
  if (is_single()) {  
    $content .=  '<div id="authorbio">';
    $content .= '<h3>About ' . get_the_author() . '</h3>';
    $content .= '<p>' . get_avatar(get_the_author_meta("user_email"), "50");
    $content .= get_the_author_description() .'</p></div>';  
  } 
  return $content;
}

You’ll see that we’ve used some functions beginning with the word “get”—get_the_author, get_avatar, get_the_author_meta, and get_the_author_description. These are functions WordPress provides to retrieve author info and avatars.

<?php the_author ?>

<?php echo get_the_author ?>

In functions.php, a filter for thematic_post will take care of attaching our function to the end of the post content:

add_filter('thematic_post','wicked_showbio', '70'),

Remember to add some CSS to your theme to make that new div look sexy.

For our last trick, we’ll take some more drastic action: we’ll remove the default list of posts from the front page and replace it with a list of our own making. We’ll grab the four most recent posts: the newest will live in a large feature area and display its post thumbnail, with the next three arranged chronologically beneath it. Imagine a similar layout to Figure 5.1.

Figure 5.1. A big feature area

add_theme_support('post-thumbnails'),

set_post_thumbnail_size(540, 300, true);
add_image_size('homepage-thumbnail', 300, 200, true);

function wicked_indexloop() {
  query_posts("posts_per_page=4");
}

function wicked_indexloop() {
  query_posts("posts_per_page=4");
  if (have_posts()) : while (have_posts()) : the_post(); ?>(1)
    … we'll do some stuff here
  <?php endwhile; else: ?>(2)
    … if there are no posts, we'll display an error
  <?php endif;
  wp_reset_query();(3)
}

query_posts("posts_per_page=4");
$counter = 1;
if (have_posts()) : while (have_posts()) : the_post(); ?>
  <div id="post-<?php the_ID() ?>" class="<?php thematic_post_class() ?>">
    <?php thematic_postheader();
    if ($counter == 1 && has_post_thumbnail()) {
      the_post_thumbnail('homepage-thumbnail'),
    } ?>
    <div class="entry-content">
      <?php the_excerpt(); ?>
      <a href="<?php the_permalink(); ?>" class="more"><?php echo more_text() ?>
↵</a>
      <?php $counter++; ?>
    </div>
  </div><!-- .post -->
<?php endwhile; else: ?>

<?php endwhile; else: ?>
  <h2>Eek</h2>
  <p>There are no posts to show!</p>
<?php endif;

function wicked_indexloop() {
  query_posts("posts_per_page=4");
  $counter = 1;
  if (have_posts()) : while (have_posts()) : the_post(); ?>
    <div id="post-<?php the_ID() ?>" class="<?php thematic_post_class() ?>">
      <?php thematic_postheader();
      if ($counter == 1 && has_post_thumbnail() && !is_paged()) {
        the_post_thumbnail('homepage-thumbnail'),
      } ?>
      <div class="entry-content">
        <?php the_excerpt(); ?>
        <a href="<?php the_permalink(); ?>" class="more">
↵<?php echo more_text() ?></a>
        <?php $counter++; ?>
      </div>
    </div><!-- .post -->
  <?php endwhile; else: ?>
    <h2>Eek</h2>
    <p>There are no posts to show!</p>
  <?php endif;
  wp_reset_query();
}

// action hook creating the index loop
thematic_indexloop();

// action hook creating the index loop
//thematic_indexloop();

// a custom homepage loop
wicked_indexloop();

// create the navigation below the content
thematic_navigation_below();

body.home div.p1 {
  font-size: 120%;
}

body.home div.p1 img {
  float: left;
  margin-right: 30px;
}

body.home div.p2 {
  clear: left;
}

body.home div.p2,
body.home div.p3,
body.home div.p4 {
  width: 270px;
  float: left;
  margin-top: 22px;
}

body.home div.p3 {
  margin-left: 30px;
  margin-right: 30px;
}

Have you ever found yourself lost in a maze of unfamiliar code, looking for a sign—any sign—of what it does and why it’s there? Worse yet, has it been code you’ve written yourself? Sure, right now you might know your code backwards and forwards, but what about in three or six months’ time when you want to update it? And what if you’re releasing your theme to the public?

Save yourself, and your users, some aggravation by leaving copious comments in your code. Bits are free!

If you have more than a few custom functions in your functions.php file, it’s probably time to start organizing them into separate files.

For example, you might want to move all your content filters into their own file. To do so, grab them out of your functions file and paste them into a new one—let’s call it functions-contentfilters.php. For extra neatness, create a new subdirectory in your theme’s directory, and give it a useful name—say, library.

Next, in your functions.php file, include it like so:

include('library/funcitons-contentfilters.php'),

Separating your functions by purpose means that you, and your theme’s users, will find it super-easy to locate your handiwork later on.

Remember, your theme will form just one part of a website. WordPress, plugins, and your theme all work together. If any of your functions’ names clash with one from a plugin or WordPress itself, there’ll be confusion—and bugs—aplenty. It’s a good idea to prefix all your function names with a reasonably unique string—the prevailing best practice in the WordPress community is to use an abbreviated form of your theme’s name, as we’ve done with our Wicked theme throughout the chapter.