Since you can define a function that can be used in several template files of your theme, a useful function to have around would be breadcrumbs. Breadcrumbs are a user-friendly navigation tool to complement your blog with. They are also good for internal linking structure, which is a sound SEO practice.

Organization First

We can write new functions and place them inside functions.php without any problems. However, as we will be writing more functions in the future, this file will start to grow. The file will become bloated, unorganized, and harder to manage.

We will use functions.php to include another function file. This external file will contain our breadcrumbs function, and other functions that are related to it. One related function for breadcrumbs will be a helper function that will generate the Html for anchor links (more on this later).

Also, instead of cluttering the main theme directory with all of our new function files, we will create a subdirectory to store them all in. This will have the added benefit of moving the entire directory into other theme designs without having to dig around looking for them in the main theme directory.

Structuring Directories and Files

Create a subdirectory inside of your main theme directory named /functions/.

Inside the new subdirectory, create a blank file named template-functions.php. We could have named this new file breadcrumbs.php, but I am planning on adding more template functions in the future.

Insert the following code into the newly created template-functions.php file and save it:

<?php

/***********************************************************
* wsf_breadcrumbs() - Shows breadcrumbs in template
***********************************************************/
function wsf_breadcrumbs() {
}

/***********************************************************
* Helper Functions for template coding
***********************************************************/
function wsf_make_link () {
}

 ?>

Right now, the functions in this file do not do anything. Don’t worry, we will be fleshing that all out below.

Also note that I prefixed my function names with wsf_. All of my functions will be prefixed this way. The reason is to avoid any conflict with pre-existing functions or plugins.

Hopefully this prefix is an unique one, and makes sense where it is coming from — in this case, wsf_ stands for WebStractions Function. Feel free to use your own prefix in place of this one.

Open up the functions.php file inside your theme directory. Most themes should have this file. If yours does not, create it.

From this point on, I am assuming that you have a basic grasp of coding Wordperfect templates and some knowledge of how Php works. Remember that Php statements must reside between the <?php and ?>

Near the top of the functions.php file, and after the opening <?php tag, add the following line of code:

   require_once('functions/template-functions.php');

The canvas is now set, let’s get on with a little coding.

Template Helper Functions

Breadcrumbs contain at least one link, or they can contain many links. Each step in building the breadcrumbs involves repetitive Html coding for anchor links.

Lets create a helper function to dynamically create the Html for the anchor link and add in some optional goodies along with it.

Edit your functions/template-functions.php file for the wsf_make_link function:

/***********************************************************
* Helper Functions for template coding
***********************************************************/
function wsf_make_link ( $url, $anchortext, $title=null, $nofollow=false ) {
   if ( $title == null ) $title=$anchortext;
   $nofollow==true ? $rel=' rel="nofollow"' : $rel = ''; 

   $link = sprintf( '%s', $url, $title, $rel, $anchortext );
   return $link;
}

This helper function takes two required parameters and two optional parameters. They are pretty much self-explanatory and you will notice that extra goody for setting the relationship of the link to Nofollow.

The helper function formats the parameters into a string variable and returns that variable for you to process further. Let’s put this function to work in our breadcrumbs function now.

The breadcrumbs() Template Function

Edit your functions/template-functions.php file for the wsf_breadcrumbs function:

/***********************************************************
* wsf_breadcrumbs() - Shows breadcrumbs in template
***********************************************************/
function wsf_breadcrumbs( $sep = '/', $label = 'Browsing' ) {

	global $post;

   // Do not show breadcrumbs on home or front pages.
   // So we will just return quickly
   if((is_home() || is_front_page()) && (!$front_page))
      return;

	// Create a constant for the separator, with space padding.
	$SEP = ' ' . $sep . ' ';

  echo '
';
	echo $label . ': ';
  echo wsf_make_link( get_bloginfo('url'), 'Home', get_bloginfo('name'), true ) . $SEP;

  if(is_single()) {
  	the_category(', '); echo $SEP;
	}
	elseif(is_page()) {
			$parent_id = $post->post_parent;
			$parents = array();
			while($parent_id) {
				$page = get_page($parent_id);
  			$parents[]  = wsf_make_link( get_permalink($page->ID), get_the_title($page->ID) ) . $SEP;
				$parent_id  = $page->post_parent;
			}
			$parents = array_reverse($parents);
			foreach($parents as $parent) {
				echo $parent;
			}
   }
   // Wordpess function that echoes your post title.
   the_title();
	 echo '

';
}

The breadcrumbs function takes two optional parameters for the crumb separator and the label which gets pre-pended. Hopefully this is all pretty much explanatory.

Currently this function will only work on single post pages and pages that you create by hand.

For single posts, this function will look like the breadcrumb at the top of this page. If I have a post that contains more than one category, then they all will be listed and separated by a comma. (Ugly, I know. Will work on a better method in the future).

For your hand generated pages, there is a loop that will recursively step through the hierarchy of parent categories. You can have a page nested three, four, or more levels deep and this loop will follow it all the way back to the top.

In the future I plan on adding loops for tags, categories, archives, etc. But for now, the two biggies are here.

Using Your breadcrumbs() Function in a Theme

This is easy to plug into any theme. Since breadcrumbs will only show up for single posts and custom pages, you will only need to add the function to your single.php and page.php files.

Add this line in your theme file where you want the breadcrumbs to appear:

   <?php wsf_breadcrumbs('»','You are here') ?>

That will generate a breadcrumb like this:

Kewl, eh?

That is about all there is to it. You just wrote some functions that you can re-use in all of your WordPress themes. Congratulations!

If you have any problems with this, let me know with a comment below.

My goal was simple — suppress the Blogroll and Meta sections in the sidebar for any page except the Home Page. Logically, I thought, just surround the sections with the conditional tag is_home() should accomplish this simple feat. The WordPress Codex even has a dynamic sidebar example for the use, pretty straight forward.

Take the following snippet of sidebar code for example. I am displaying a list of recent posts, immediately followed by the conditional blogroll.

Latest Blog Entries

      <?php query_posts('showposts=10'); ?>
      <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
<a href="<?php the_permalink() ?>"><?php the_title() ?></a>

      <?php endwhile; endif; ?>
      


   <?php if(is_home() && !is_paged()): ?>

Blogroll

      <?php  wp_list_bookmarks('title_li=&categorize=0'); ?>
      


   <?php endif; ?>

The above code returns true for is_home() on each and every non-home page or post. Why is that? This is where I lost quite a bit of hair, mostly from the left side of my head and therefore most of the insulation to the thinking part of the brain. Good thing the heat works around here.

It took quite a lot of searching. This is not an easy thing to Google for, but eventually came across some answers.

The culprit in the code was the use of query_posts() in the recent posts widget. If I swapped the positions of the two widgets, is_home() functioned correctly. The query_posts() function has an obscure little bug if you do not destroy it properly with a call to wp_reset_query().

There isn’t any documentation on wp_reset_query() in the Codex, so I will cite the comment heading from the WordPress core file, query.php, which this function is from:

wp_reset_query() destroys the previous query and setup a new query. This should be used after query_posts() and before another query_posts(). This will remove obscure bugs that occur when the previous wp_query object is not destroyed properly before another is setup.

So I added that function immediately following the endwhile in the recent comments widget, and bam, everything was right in the universe again.

      ....
      <?php query_posts('showposts=10'); ?>
      <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
         <li><a href="<?php the_permalink() ?>"><?php the_title() ?></a></li>
      <?php endwhile; endif; ?>
      <?php wp_reset_query(); ?>
      ....

Searching for references to wp_reset_query() in the WordPress core files reveals only one instance of usage. That instance, oddly enough, is in the widget.php function for displaying the recent entries widget. Imagine that!

Reviewing the code, however, I made another discovery. Instead of using query_posts(), they create a new WP_query object to cycle through the posts and generate the recent entry list items. They use the new object in order to preserve the original query in the main loop, the loop that displays your posts on page. More importantly, the new object preserves the values of is_home() and other conditional tags — the use of wp_reset_query is really not needed here. Seems to be a left over from a previous version and not edited out of the core code.

In order to do this the wordpress-ian way, I recoded my sidebar widget for recent posts (sans wp_reset_query):

Latest Blog Entries

      <?php $r = new WP_Query(array('showposts' => '10', 'what_to_show' => 'posts',
	         'nopaging' => 0, 'post_status' => 'publish', 'caller_get_posts' => 1)); ?>
      <?php if ($r->have_posts()) : while ($r->have_posts()) : $r->the_post(); ?>
<a href="<?php the_permalink() ?>"><?php the_title() ?></a>

      <?php endwhile; endif; ?>
   

If you follow my logic in tracking down this little bugger, you will notice that my first resource to check was the conditional tag documentation in the Codex. Sadly, there is no mention of the consequences you will encounter by using query_posts() which alters the original page loop.

The WP support forum is filled with questions of ‘why is this not working’. Some go unanswered, some they fix and leave no reason how, some get the ‘review the conditonal tags documentation’ buddy, and so on. It took a lot of searching to get a whiff of what I needed to do to correct the situation.

My suggestion is to at least insert a caveat into the documentation for conditional tags warning of what will happen to those tags if another query_posts() is called. This is the first place people will actually look for help after all. And it would probably save a lot of people’s time in the long run, not only the people seeking it, but the people offering a solution as well.

UPDATE: The discussion for the creation of wp_reset_query() function can be found at http://trac.wordpress.org/ticket/4741 if you are interested. Thanks to Stephen’s post Automated Indexes and wp_reset_query() at Nerdaphernalia for pointing this out.

I am now starting from scratch with WordPress 2.7 — this is the first time I have used this later version. The backend Admin area was totally rearranged. I rather like it though, especially the way Posts are laid out. It felt more comfortable to use to me.

What follows is an abstract for some of the high-points during the creation of this blog. More for documentation purposes, and in the future will be updated to include links to newer posts in which I can go into more detail.

WordPress Settings

Moved WordPress to the root domain per Codex article.

Turned off the Visual Editor in profile settings.

Custom structure for Permalinks /%category%/%postname%/

WordPress Plugins

Akismet, of course.

That is about it. Pretty much lean and mean.

WordPress Theme (Webstractive)

Early stages of theme development

Future Work

Will update this post as needed, add in screenshots, document procedures, etc. yada, yada. As mentioned in my inaugural post, there is an undocumented ‘snafu’ with the is_home() and is_front() functions in the WP core – more on that later too.