Archives

Breadcrumb Templates

Posted by in

Introduced in version 4.0.0, breadcrumb templates replace the anchor templates and the prefix and suffix settings. Most breadcrumb types have two breadcrumb templates. The first breadcrumb template is used when the breadcrumb is linked, the second is for when the breadcrumb is not linked (e.g. when it is the current item and “Link Current Item” is not set). An example for the Page post type:

  • “Page Template” contains the HTML Breadcrumb NavXT will used on breadcrumbs representing a post (instance) of the Page post type when they need to link to the Page they represent.
  • “Page Template (unlinked)” contains the HTML Breadcrumb NavXT will used on breadcrumbs representing a post (instance) of the Page post type that should not be linked (e.g. when it is the current item and “Link Current Item” is not set).

As of Breadcrumb NavXT 5.3.0, the default values for all instances of both breadcrumb templates are Schema.org BreadcrumbList compliant.

Breadcrumb templates accept the following HTML tags:

  • Anything allowed by wp_kses_allowed_html('post')
  • a and the following attributes: href, title, class, id, media, dir, relList, rel, lang, aria-hidden, data-icon, itemref, itemid, itemprop, itemscope, itemtype, xmlns:v, typeof, property, vocab, translate, and lang
  • img and the following attributes:alt, class, id, height, width, align, lang, src, srcset,aria-hidden, data-icon, itemref, itemid, itemprop, itemscope, itemtype, xmlns:v, typeof, property, vocab, and lang
  • span and the following attributes: title, class, id, dir, align, lang, xml:lang, aria-hidden, data-icon, itemref, itemid, itemprop, itemscope, itemtype, xmlns:v, typeof, property, vocab, translate, and lang
  • h1 and the following attributes: title, class, id, dir, align, lang, xml:lang, aria-hidden, data-icon, itemref, itemid, itemprop, itemscope, itemtype, xmlns:v, typeof, property, vocab, translate, and lang
  • h2 and the following attributes: title, class, id, dir, align, lang, xml:lang, aria-hidden, data-icon, itemref, itemid, itemprop, itemscope, itemtype, xmlns:v, typeof, property, vocab, translate, and lang
  • meta and the following attributes: content, property, vocab, and itemprop

Note that additional, HTML tags and attributes can be added via the bcn_allowed_html filter.

Breadcrumb templates also accept dynamic tags. These are replaced by Breadcrumb NavXT by the proper values when generating the breadcrumb trail. Breadcrumb templates accept the following dynamic tags:

  • %title% The title for the breadcrumb, typically the page title/name, tags are stripped and it is run through esc_attr().
  • %htitle% The title for the breadcrumb, typically the page title/name, tags are left intact.
  • %link% The URL to the resource (page) that the breadcrumb represents.
  • %type% The breadcrumb type. This is output as a comma delimited list, useful for setting as a group of classes for styling.
  • %ftitle% The title of the breadcrumb typically the page title/name, tags are stripped and it is run through esc_attr(). This version is never run through bcn_breadcrumb::title_trim(). This tag was introduced in version 4.3.0. This tag has been deprecated since 5.7.0.
  • %fhtitle% The title for the breadcrumb, typically the page title/name, tags are left intact. This version is never run through bcn_breadcrumb::title_trim(). This tag was introduced in version 4.3.0. This tag has been deprecated since 5.7.0.
  • bcn-aria-current This tag is replaced with aria-current="page" when the breadcrumb represents the current page. Otherwise, this tag is replaced by an empty string. This facilitates WAI-ARIA Breadcrumb support. This tag was introduced in version 6.3.0.

Note that additional, custom dynamic tags can be added via the bcn_template_tags filter.

Related Articles

Updated:

How to Add a Custom Breadcrumb Template Tag

Posted by in Guides

Since version 4.4.0, it has been possible to add additional custom template tags to supplement the defaults included in Breadcrumb NavXT. Adding a custom template tag is relatively easy. All one has to do is write a function that hooks into the bcn_template_tags filter and adds the new template tag.

bcn_template_tags has three parameters, two for helping identify the resource the breadcrumb represents, and one for the actual replacement set. Today, we’ll focus on the first parameter, the $replacements array. This associative array has the template tag as the key and the value is the actual value that should replace the tag in breadcrumbs. To add a new template tag, simply add a new key-value pair to the array and return the modified $replacements array.

For example, to add a breadcrumb template tag that inserts the current theme’s directory, one could use the following:

function my_bcn_template_tag($replacements, $type, $id)
{
    //Add the %template_directory% template tag
    $replacements['%template_directory%'] = get_bloginfo('template_directory');
    //Return our new set of templates and replacements
    return $replacements;
}
add_filter('bcn_template_tags', 'my_bcn_template_tag', 3, 10);

In the code above, %template_directory% is the breadcrumb template tag being added; its value is retrieved using the get_bloginfo() function. Simple, right?

-John Havlik

[end of transmission, stay tuned]

Remove the Link in a Breadcrumb

Posted by in Guides

A topic that comes up time to time in support requests is how to unlink a breadcrumb. Typically this is due to having an empty page that exists to facilitate a logical hierarchy. Naturally, linking to this blank page in the breadcrumb trail is not useful. While it is bad form to have a breadcrumb in the breadcrumb trail that is not linked, there is a filter that can facilitate this behavior.

The presented solution is a simplistic example for a single page. However, it can be extended for multiple pages, or taxonomy terms. Finally, rather than being hard-coded, the IDs could come from a post_meta/term_meta field.

The Code (Breadcrumb NavXT 6.5)

Introduced in Breadcrumb NavXT 6.5, the bcn_breadcrumb_linked filter makes changing the linked status quite simple:

add_filter('bcn_breadcrumb_linked', 'my_breadcrumb_url_stripper', 3, 10);
function my_breadcrumb_url_stripper($linked, $type, $id)
{
	if(in_array('post-page', $type) && (int) $id === MYPAGEID)
	{
		return false;
	}
	return linked;
}

The Code (Pre-Breadcrumb NavXT 6.4)

Due to changes introduced in Breadcrumb NavXT 6.4, the below only works with versions of Breadcrumb NavXT prior to 6.4:

add_filter('bcn_breadcrumb_url', 'my_breadcrumb_url_stripper', 3, 10);
function my_breadcrumb_url_stripper($url, $type, $id)
{
	if(in_array('post-page', $type) && (int) $id === MYPAGEID)
	{
		$url = NULL;
	}
	return $url;
}

After placing this code into your site specific plugin, you will need to update one part of it. Just replace MYPAGEID with the ID of the page you want to remove the link to. That’s it. Simple, right?

-John Havlik

[end of transmission, stay tuned]

Link to a Page Rather Than the Category Archive in a Breadcrumb

Posted by in Guides

A topic that frequently comes up in the support forums is how to have a breadcrumb representing a category link to a Page (instance of the Page post type) rather than a category archive. Since this is not natively supported by WordPress, Breadcrumb NavXT does not natively support it. However, there is a filter that can facilitate this behavior.

The presented solution is a simplistic example for a single category. However, it can be extended for multiple categories, or taxonomy terms. Finally, rather than being hard-coded, the IDs could come from a term_meta field.

The Code

add_filter('bcn_breadcrumb_url', 'my_breadcrumb_url_changer', 3, 10);
function my_breadcrumb_url_changer($url, $type, $id)
{
	if(in_array('category', $type) && (int) $id === MYCATID)
	{
		$url = get_permalink(PAGEID);
	}
	return $url;
}

After placing this code into your site specific plugin, you will need to update two portions of it. Replace MYCATID with the ID of the category you want to change the link on, and replace PAGEID with the page you wish for the breadcrumb to link to. That’s it. Simple, right?

-John Havlik

[end of transmission, stay tuned]

Using bcn_display() and bcn_display_list()

Posted by in

bcn_display is the main display function for Breadcrumb NavXT. It will generate a breadcrumb trail for the current page (resource, not post type). The following is the function’s prototype

bcn_display($return = false, $linked = true, $reverse = false, $force = false)
  • $return the first parameter, it is a boolean and controls whether or not the breadcrumb trail is returned or echoed. Set to true to return the assembled breadcrumb trail string. It defaults to false if no value is passed in.
  • $linked the second parameter, it is a boolean and controls whether or not the breadcrumbs in the breadcrumb trail are linked (if anchors are generated or not). Set to false to get a string without anchors. It defaults to true if no value is passed in.
  • $reverse the third parameter, it is a boolean and controls the order the breadcrumbs are arranged within the trail. Set to true to have the current item’s breadcrumb show up first in the breadcrumb trail (this is revered of the normal behavior). It defaults to false if no value is passed in.
  • $force the fourth parameter, it is a boolean and controls whether or not generation of the breadcrumb trail should be forced (e.g. should the internal caching mechanism be bypassed). It defaults to false if no value is passed in. This parameter was introduced in Breadcrumb NavXT 5.6.0.

bcn_display_list() accepts the same parameters as bcn_display(). The difference is in how the breadcrumb trail is assembled. bcn_display() places a breadcrumb separator between breadcrumbs in the trail. bcn_display_list() wraps each breadcrumb with <li> tags.

Related Articles

Updated: