eironae: [ahy-ruh-nee]

Explanation & History

First and foremost, I did not write this plugin. Credit for that goes to Dan Peverill. He long ago stopped supporting/developing it, and graciously allowed me to re-release it for public consumption after I contacted him looking for the old config instructions I knew used to be out there.

Why do I want to regurgitate an old, unsupported plugin? Because I use it…a lot, because it still works beautifully in WP 2.3.1, and because as far as I can tell it’s the most graceful solution out there for WP breadcrumbs.

I’m not a programmer by a long shot, but I will attempt to support any issues you have to the best of my ability. My hope is the people who used this plugin previously will seep out of the woodwork with valuable insights and make themselves useful.

Most of the instructions here are taken verbatim from the archived version of the original support site. I will edit as necessary as time permits.

Installation

Start by downloading the latest version. Then to install, simply unzip breadcrumb.php to your plugins directory, and enable the plugin in your admin panel. For information on how to use the breadcrumb, scroll down to basic usage.

What’s a Breadcrumb?

A breadcrumb is a navigation trail that leads from the user’s current location in your web site, back to the home page. This is useful for larger web sites that have deeply nested pages or sections in their site. For a live demo of the breadcrumb, simply look around on this site. You’ll see the breadcrumb located just under the header. What you see on my site is only the basic usage of the breadcrumb.I’ll add breadcrumbs to this site and produce several more real-world examples shortly. Feel free to email me with examples of your work and I may include them here. Screenshot(s) detailing more customization:

From Nazgul’s blog:

(example no longer in use on target site, but example is still valid)

Basic Usage

This plugin will allow you to display a breadcrumb navigation anywhere on your site. It’s usage is simple. Wherever you want the breadcrumb navigation to display, simply call the breadcrumb() function:

<?php breadcrumb(); ?>

If you’d like to use the breadcrumb in your titlebar, no problem, there’s a function for that as well:

<title><?php breadcrumb_title(); ?></title>

If you want more control over how the breadcrumb is displayed, there are a few options. You can specify a different separator, text to put before a crumb, and text to put after a crumb. So displaying the breadcrumb as a unordered list, for example, would loook something like this:

<?phpif (has_breadcrumb()){
echo ‘<ul class=”breadcrumb”>’;
// Note that any and all of these parameters are optional.
breadcrumb(“”, “<li>”, “</li>”, ‘<li class=”selected”>’);
echo “</ul>”;
}
?>

Using a different separator between your crumbs would look like this:

<?php breadcrumb(“:”); ?>

Advanced Usage

Sometimes, more options are required. A lot of users love to customize every inch of their web site, and I’ve provided a way to do that with the breadcrumb. Through advanced options, you can control just about any part of the breadcrumb in combination with its filtering system (scroll down for filtering information).

Advanced options include:

• sep (breadcrumb() only) : Separator between crumbs.
• before (breadcrumb() only) : Text before a crumb.
• after (breadcrumb() only) : Text after a crumb.
• last (breadcrumb() only) : Text before the last crumb.
• echo (breadcrumb() only) : Set to false to return the breadcrumb rather than printing it.
• home_always (breadcrumb() and get_breadcrumb()) : Set to true to always display the Home crumb.
• home_never (breadcrumb() and get_breadcrumb()) : Set to true to never show the Home crumb (this is the same as removing the get_breadcrumb_home filter).
• home_title (breadcrumb() and get_breadcrumb()) : Change the text displayed for the Home crumb.
• link_all (breadcrumb() and get_breadcrumb()) : Set to true to link all crumbs.
• link_none (breadcrumb() and get_breadcrumb()) : Set to true to link no crumbs.

You can use advanced options by specifying their key/value pairs within the breadcrumb() function:

<?php breadcrumb(“home_always=true&link_all=true”); ?>

The Breadcrumb Itself

The breadcrumb is built as an array of strings. The breadcrumb() function may or may not offer what you’re looking for in terms of customization. If that’s the case, you can use the breadcrumb array itself by calling the get_breadcrumb() function and applying any customization you want to each individual crumb:

<?php$breadcrumb = get_breadcrumb();foreach($breadcrumb as $crumb)
{
// $crumb is a string.
echo “- “.$crumb.“<br />”;
}
?>

Filtering the Breadcrumb

The breadcrumb plugin, much like any other part of WordPress, is filter based. Each part of the breadcrumb, whether it be the home page, the categories, and so on, are attached by filters. This allows you to do whatever you like to the breadcrumb, such as removing and adding new filters. You can add or remove any filter either specifically for a template by using your functions.php template file, or by creating a custom plugin yourself. In fact, other plugins are able to extend the breadcrumb if they so desire. Here are the default filters:

add_filter(“get_breadcrumb”, “get_breadcrumb_home”, 1, 2);add_filter(“get_breadcrumb”, “get_breadcrumb_category”, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_page”, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_single”, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_date”, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_author”, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_search”, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_404″, 5, 2);
add_filter(“get_breadcrumb”, “get_breadcrumb_paged”, 5, 2);

To remove a filter:

remove_filter(“get_breadcrumb”, “get_breadcrumb_home”);

To add a filter:

add_filter(“get_breadcrumb”, “breadcrumb_search_ext”, 10, 2);/*** @param array  The breadcrumb itself.
* @param array  Advanced parameters passed by the user.
*/
function breadcrumb_search_ext($breadcrumb, $params)
{
if (is_search())
{
// Do whatever you like to the breadcrumb. The user is viewing the search page.
// Be sure to check the $params for user specified options, such as $params[”link_all”] if crumbs should always be linked.
}
return $breadcrumb;
}

Release History

• 0.5.2 [11/26/2007] : Re-release plugin under new management.
• 0.5.1 [06/14/2006] : Fixed a few pagination bugs.
• 0.5 [06/13/2006] : Added advanced formatting options for breadcrumb() and get_breadcrumb, such as sep, before, after, last, echo, home_always, home_never, home_title, link_all, and link_none. Added breadcrumb_title() function for displaying the breadcrumb in a web site’s title (browser’s titlebar).
• 0.4.1 [06/12/2006] : Multiple calls to breadcrumb(); now working properly.
• 0.4 [06/11/2006] : Added pagination crumb, added option text before current crumb (users location), fixed home page crumb while paging, fixed 404 crumb, fixed month link, fixed day link.
• 0.3 [06/10/2006] : Fixed reverse order bug for page and category crumbs.
• 0.2 [06/10/2006] : Changed the breadcrumb to filter based, allowing easy extension and customization.
• 0.1 [06/09/2006] : Initial beta release.