Breadcrumbs Box

The Breadcrumbs Box enables you to deliver Schema-enhanced breadcrumb trails on your Thesis-powered website.

It is not a one-size-fits-all solution that “just works.” Every site’s information hierarchy is different, and because of this, the Breadcrumbs Box requires thoughtful integration.

Ultimately, you are responsible for setting it up and implementing it precisely how you want.

How to Add Breadcrumbs to Your Thesis Skin

After installing and activating this Box, the next logical step is to add breadcrumbs to one or more templates so you can see how they work.

You can use the Thesis Skin HTML Editor to add breadcrumbs to your design.

Specifically, you’ll need to add the Breadcrumbs Box to each template where you’d like breadcrumbs to appear. No matter which Thesis Skin you’re using, the following core templates are prime candidates for breadcrumbs:

• Single
• Page
• Archive

And if you’re using a static front page, you’ll probably want to add breadcrumbs to the Home template as well.

Watch this video, and I’ll show you precisely how I add the Breadcrumbs Box to my templates ↓

I’ll show you everything you need to do to set up the Breadcrumbs Box.

Most likely, your Thesis Skin also came with some custom templates. Depending on how you use these custom templates, you’ll need to decide which ones require breadcrumbs and add them accordingly.

Related: How to add a Box to a template

Ultimately, the way you incorporate breadcrumbs is up to you, but a good starting point is to simply replace the Nav Menu on templates where you want breadcrumbs to display.

By doing this, you’ll establish a funnel-based navigation structure that keeps things simple for visitors and also keeps them focused on your content (rather than on navigational decisions about where to go next).

Breadcrumbs Box Settings

Now that you’ve got breadcrumbs appearing on one or more templates and can see how they work, you may notice some things you’d like to change.

Visit the Breadcrumbs settings page at Thesis Admin → Boxes → Breadcrumbs and make sure the options are set according to your preferences:

• Custom home breadcrumb text — Set to your WordPress Site Title by default, but you can specify custom text here
• Custom home breadcrumb link URL — Set to your home page by default, but you can specify a custom link URL here
• Include Category in Post Trails? — Select this option if you’d like to include a category link in the breadcrumb trail for each Post

Setting Breadcrumb Text

By default, the Breadcrumbs Box will use the Post Title as the breadcrumb text for a specific Post or Page.

Generally speaking, however, post titles are too long to be useful as breadcrumbs (which should be both concise and precise).

And this is why the Breadcrumbs Box adds a new post meta box to the WordPress post editor¹ that enables you to enter custom breadcrumb text:

Refine your site’s navigation with custom breadcrumb text!

CSS Targeting and Common Customizations

There’s no doubt you’ll want to customize your breadcrumbs to get them looking precisely how you want. Use the following element targeting in your Custom CSS to make customization a breeze!

.crumbs {
	// main <div> containing the breadcrumbs
	.crumbs-item {
		// every item in the breadcrumb trail (including separators)
	}
	.crumbs-crumb {
		// every item in the breadcrumb trail (excluding separators)
	}
	.crumbs-sep {
		// character separators in the breadcrumb trail
	}
	a {
		// all links
		&:hover, &:active {
			// hover and active behavior on all links
		}
		&.crumbs-home {
			// home item link only
		}
	}
}

The code above is in SCSS format and will work with any SCSS-enabled Thesis Skin.

To center the breadcrumb trail:

.crumbs {
	text-align: center;
}

Advanced Customizations to Modify Breadcrumb Behavior

Use the PHP solutions below to bend Breadcrumbs Box output to your iron will

The Breadcrumbs Box “just works” after you add it to your templates, but you may still want to change some things based on how you use your breadcrumb trails.

Use the done-for-you tutorials below to modify breadcrumb output and behavior like an absolute ninja.

Pro tip: You’ll need to use your master.php or custom.php file to implement these solutions.

How to Change the Breadcrumb Separator

The Breadcrumbs Box includes a simple string filter, thesis_breadcrumbs_separator, that enables you to change the character separator that appears between breadcrumbs.

For example, to change the separator from → to >, you could add the following PHP code to your master.php or custom.php file:

add_filter('thesis_breadcrumbs_separator', 'custom_breadcrumb_separator');

function custom_breadcrumb_separator($separator) {
    return '>';
}

“Second” Position Breadcrumb Injection

For example, if you’re running a custom archive resource page (like this one), your default breadcrumb for this page will simply be:

• Your Site → Page Title

But that breadcrumb trail is probably not ideal, simply because this page is effectively a category/tag archive page—and category/tag archive pages are directly related to your blog.

In this case, a more pertinent breadcrumb trail might be:

• Your Site → Blog → Page Title

The Breadcrumbs Box includes an array filter, thesis_breadcrumbs_second, that makes this sort of refinement possible.

To resolve the situation illustrated above, you could add this PHP code to your master.php or custom.php file:

// Front end modifications should only be run when the environment is ready
add_action('template_redirect', 'custom_breadcrumbs');

function custom_breadcrumbs() {
    if (is_page('my-custom-archive-resource-page-slug'))
        add_filter('thesis_breadcrumbs_second', 'breadcrumb_custom_second');
}

function breadcrumb_custom_second($crumbs) {
    $crumbs['Blog'] = '/blog/'; // Blog is the breadcrumb text, and /blog/ is the associated URL
    return $crumbs;
}

“Zeroth” Position Breadcrumb Injection

If you’re running nested WordPress installations on your site, you may want to inject a breadcrumb in the zeroth position—before the rest of the breadcrumb trail.

The main Thesis page on DIYthemes, for example, runs on a completely separate WordPress installation, and thus breadcrumbs on this part of the site all start with THESIS.

Of course, this is not ideal since the Thesis sub-section is merely part of the larger DIYthemes website.

To fix this, the Thesis sub-section uses the thesis_breadcrumbs_prepend array filter to add a DIYthemes link to the front of the breadcrumb trail:

add_action('template_redirect', 'custom_breadcrumbs');

function custom_breadcrumbs() {
    add_filter('thesis_breadcrumbs_prepend', 'breadcrumb_custom_prepend');
}

function breadcrumb_custom_prepend($crumbs) {
    $crumbs['DIYthemes'] = 'https://diythemes.com/';
    return $crumbs;
}

With this filter arrangement in place, all breadcrumbs in the Thesis sub-section will be prepended with a link to the DIYthemes home page.

Breadcrumb Trail Modification

You may encounter situations where you cannot use the second or prepend filters to get the breadcrumb trail you want. For example, you might need to remove a certain breadcrumb from a particular page.

This is where the thesis_breadcrumbs_trail array filter gives you absolute control over the final breadcrumb output. Here’s how it works…

Before a breadcrumb trail is output to the page, it is represented by a simple array with indices ranging from 0 to (n – 1), where n is the total number of crumbs in the trail:

DIYthemes → Thesis → Blog → Post Title
    0          1       2        3

For this example, let’s remove the Blog breadcrumb from the trail shown above. Here’s how you can do it:

add_action('template_redirect', 'custom_breadcrumbs');

function custom_breadcrumbs() {
    add_filter('thesis_breadcrumbs_trail', 'modify_breadcrumb_trail');
}

function modify_breadcrumb_trail($crumbs) {
    unset($crumbs[2]);
    return $crumbs;
}

Because the Blog breadcrumb appears in the third position, we need to unset() the number 2 index to remove this item (because crumb numbering starts at zero!).

Please note that you can also use this approach to add breadcrumbs, but you should always try to use the second or prepend filters for this purpose first.

Custom Breadcrumb Branches

There may be areas of your site where you don’t want an entire breadcrumb trail to display. For example, you might have pages where you’d like to add a localized breadcrumb trail to navigate within a particular content funnel.

By default, the Breadcrumbs Box traces your site’s hierarchy all the way back to the home page. You can use the thesis_breadcrumbs_branch string filter to define a “stopping point”—and thus establish a new root breadcrumb wherever you like.

To illustrate this, let’s assume we have a content funnel with a top-level page that has an ID of 1456. The goal is to have all pages underneath this page (hierarchically nested descendants) display a breadcrumb trail with the top-level page as the root crumb.

Here’s how it works:

add_action('template_redirect', 'custom_breadcrumbs');

function custom_breadcrumbs() {
    global $thesis;
    if ($thesis->wp->is_tree(1456))
        add_filter('thesis_breadcrumbs_branch', 'custom_breadcrumb_branch');
}

function custom_breadcrumb_branch() {
    return 1456;
}

Two things to note in the code above: First, the custom_breadcrumb_branch() function defines a new breadcrumb branch based on the page with ID 1456.

However, if this was the only thing you declared in your code, every breadcrumb trail on your site would be affected and would have page 1456 as the root breadcrumb. (And any pages not hierarchically nested under page 1456 would simply return an empty breadcrumb trail—not ideal!)

The solution is to only define breadcrumb branches conditionally. That’s where the Thesis WP API is_tree() method is extremely handy.

In this example, the $thesis->wp->is_tree(1456) conditional ensures that the breadcrumb branch modification is only applied if the current page is a descendant of the page with ID 1456.

As you can see, breadcrumb “branching” is really a two-part process—define the branch, and then define the conditions under which the branch is applied.

Date-based Breadcrumb Trail for Posts:

If you run your blog with date-based archives, you may want to consider a date-enhanced breadcrumb trail for posts.

Here’s how you can use the thesis_breadcrumbs_second filter to add a year and month to your breadcrumb trails:

add_action('template_redirect', 'front_end');

function front_end() {
	if (is_single())
		add_action('thesis_breadcrumbs_second', 'date_based_crumbs');
}

function date_based_crumbs($crumbs) {
	global $post;
	if (!is_object($post) || empty($post->post_date))
		return $crumbs;
	$date = date_parse($post->post_date);
	if (empty($date) || empty($date['year']) || empty($date['month']))
		return $crumbs;
	$crumbs[$date['year']] = "/{$date['year']}/";
	$crumbs[date('F', strtotime($post->post_date))] = "/{$date['year']}/". sprintf('%02d', $date['month']). '/';
	return $crumbs;
}