Breadcrumbs Box

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

Basic Setup

Unlike other breadcrumb implementations, the Breadcrumbs Box is not an automatic, one-size-fits-all solution. It requires thoughtful integration, and ultimately, you’ll be responsible for setting it up precisely how you want.

You oughta know: The Breadcrumbs Box is considered premium because we work directly with customers to ensure each implementation is perfectly-tailored to their site’s needs.

After installing and activating this Box, you won’t notice any difference on your site. That’s because you’ll still need to go through a setup and implementation process.

The first step is to visit the Breadcrumbs settings page at Thesis AdminBoxesBreadcrumbs and make sure the defaults 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

The next step is to begin implementing breadcrumbs in your design.

How to Add Breadcrumbs to Your Thesis Skin

You’ll need to 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.

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. However, 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 locked in on your content (rather than on navigational decisions about where to go next).

Setting Breadcrumb Text

By default, the Breadcrumbs Box will use the Post Title as the breadcrumb text for a specific 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 editor1 that enables you to enter custom breadcrumb text:

Thesis Breadcrumbs Box post meta

Refine your site’s navigation with custom breadcrumb text!

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 '>';
}

Breadcrumb Path Refinements

Depending on how your site is configured, it may be necessary to refine certain breadcrumb paths for accuracy and usability.

“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.

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
	}
	.crumbs-home {
		// home item in the breadcrumb trail
	}
	a {
		// all links
		&:hover, &:active {
			// hover and active behavior on all links
		}
	}
	a.crumbs-crumb {
		// crumb links 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;
}

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;
}

Changelog

  • 0.9 — Released August 22, 2019
    • Added thesis_breadcrumbs_trail filter to enable editorial control of final breadcrumb trail output
    • Added output flag to array_reverse() calls to preserve numeric indices for better WordPress permalink compatibility
  • 0.8 — Released August 21, 2019
    • Automatic custom post type breadcrumb trails
    • Improved home URL handling
    • Rearranged page type checks in order of decreasing relevance
  • 0.7 — Released August 15, 2019

1 This works with both the Gutenberg and Classic Editors.