Writing a WordPress Function: breadcrumbs()

A WordPress theme can optionally use a functions file, which resides in the theme subdirectory and is named functions.php. This file basically acts just like a WordPress plugin, and if it is present in the theme you are using, it is automatically loaded during WordPress initialization.

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( '<a href="%s" title="%s"%s>%s</a>', $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 '<div class="breadcrumbs">';
  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 '</div>';
}

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('&raquo;','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.