Documentation

Notice: Information regarding the core classes is available in the source code (nearly every line of code has an accompanying comment line). Users interested in the inner workings of the core classes should check out the Github project for Breadcrumb NavXT.

Table of Contents

  1. Using Breadcrumb NavXT
    1. Using the Settings Page
    2. Using the Widget
    3. Using bcn_display() and bcn_display_trail()
  2. Hook Reference
    1. Action Reference
    2. Filter Reference
  3. Code Examples
    1. CSS Styling
    2. Direct Class Access

Using Breadcrumb NavXT

Using the Settings Page

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.

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

Related Articles

Using bcn_display_json_ld()

bcn_display_json_ld is a display function for Breadcrumb NavXT that generates Schema.org BreadcrumbList compliant JSON-LD markup. It will generate a breadcrumb trail for the current page (resource, not post type). The following is the function’s prototype

bcn_display_json_ld($return = false, $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.
  • $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.

Using bcn_display() and bcn_display_list()

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

Using the Widget

Since version 3.0.0, Breadcrumb NavXT has shipped with a built in WordPress sidebar widget. In Breadcrumb NavXT version 3.5.0 the included widget was rewritten and is multi instance capable. The widget allows you to place a breadcrumb trail in your theme without touching any of your theme’s files. Since Breadcrumb NavXT has a two different display functions (bcn_display() and bcn_display_list()), along with three input variables for these functions ($return, $linked, $reverse), the widget has a few settings available to the user.

Currently, the following settings are available:

  • A field to enter a title for the output widget, this works just like the title on any other widget.
  • Whether to output the trail as a list or not. If checked, the output trail will be placed in an unordered list, with each breadcrumb belonging to its own list element.
  • Whether to link the breadcrumbs or not. If checked (default), each of the breadcrumbs in the breadcrumb trail will have a hyperlink.
  • Whether to reverse the order of the trail or not. If checked, the breadcrumb trail will be output in reverse order (the leftmost breadcrumb (or first breadcrumb in a list output) will be the breadcrumb for current page).
  • Whether to hide the trail on the front page or not. If checked, the breadcrumb trail for the front page of your site will not be displayed (e.g. when is_front_page() evaluates to true).

The widget still uses the settings values specified in the Breadcrumb NavXT settings page to define its behavior while filling the breadcrumb trail.

on

437 thoughts on “Documentation

  1. Hi John,

    Thanks for this good plugin. Now I have one below query.

    On my news details page currently news slug is displaying into url. Now I want to display this slug into breadcrumb by using this plugin. I have used some bcn_display function but it is not displaying.

    Can you please help me and let me know which func/code I can apply on news details template so news slug will display into breadcrumb.

    I am waiting for your reply.

    Thanks,
    Sunil

  2. Hi there,

    I’m using your plugin within our companies intranet and there are some problems with categories und sub-categories.

    cat_A
    sub-cat_A1
    sub-cat_A2
    sub-sub-cat_A2_1
    sub-sub-cat_A2_2
    sub_cat_A3
    sub-sub-cat_A3_1
    sub-sub-cat_A3_2
    sub_cat_A4

    The breadcrumbs for an article in sub-sub-cat_A3_2 are displaying correctely BUT the breadcrumbs for an article of sub-sub-cat_A2_1 not (same category structure). In this case there is only sub-cat_A2 displaying, the rest is missing after opening the article…

    Can somebody help me?

    • Hi Nick,

      Is the post an explicit member of more than just the “sub-sub-cat_A2_1” category (e.g. an explicit member of “sub-cat_A2” and an explicit member of “sub-sub-cat_A2_1”)? If that is the case, I recommend changing the post to be only an explicit member of “sub-sub-cat_A2_1” (it will be an implicit member of the parent categories of “sub-sub-cat_A2_1”). You may also try the master branch of Breadcrumb NavXT on GitHub, its term selection behavior has changed slightly that may fix this for you.

      -John Havlik

      • Yes, the article was a member of more than just the sub-sub-category. I changed it so the article is explicit member of tha last category in the row and it works great! Good to know (explicit vs. implicit)

        THX A LOT! :)

  3. Hello,

    So far I love this plugin. I have one question st this time. Currently on our site, that is in development, all posts are classified under the category news. From the news page visitors can select blogs to read. For example when someone clicks a blog the breadcrumb will read home/news/blog title just as it should. The issue is though when someone tries to click the “news” link in the breadcrumbs it takes them to the page home/categories/news. This is not right. I want it to take the visitor directly back to home/news minus category. How can this be done.

    Thanks in advance

    • Hi Stephen,

      Breadcrumb NavXT uses the get_term_link() function to link to term archives (e.g. categories). You will need to hook into that function and remove the ‘/categories’ from the URL it returns. If you don’t want to affect every category link, you can always use the bcn_breadcrumb_url filter. See the documentation for examples of how to use that filter.

      -John Havlik

      • Hello John,
        could you please guide me to this function? I can’t find a get_term_link() anywhere in the plugin’s php files. And as a non-native speaker it is quite hard to understand every line in the documentation or settings helper texts…
        TIA
        Peter

    • In general, it is considered bad form to hide a category. It is possible, though you have to write a hook into the bcn_after_fill action and remove the unwanted category breadcrumb. To link all of the breadcrumbs in the breadcrumb trail (e.g. to link the current item, which is not usually linked), you need to ensure the “Link Current Item” setting is checked in the Breadcrumb NavXT settings page.

      -John Havlik

  4. Hi John,

    I like the plugin very much and was able to customise the looks of it very well. However, how can I hide displaying the current post title in the breadcrumbs? I tried reading the documentation but did not figure it out. There are also 4 websites describing it and none of the steps have worked.

    Thanks!
    Andrej

  5. NavXT follows the path as defined in “reading settings -> posts page.”

    My website uses a custom home page, that I do not set in “reading settings.” Doing so, would override the custom page I built.

    Is there a hook or method of letting NavXT understand that a particular page is my main (one and only) blog page?

  6. Hi John –

    Your plug-in was exactly what I needed for my site… Easy to install, easy to configure. Thanks for this! I’m experiencing some weirdness w/ how the Titles of pages are carrying through to hte plug-in… it appears that most Titles include an indentatin directly after the title, which adds a weird space..

    Check this webpage for a sample: Website sample

    I checked your guide which details how to shorten the length of text displayed in breadcrumbs, however it still included that indent..

    Any ideas of what CSS styles I can apply to .breadcrumbs to close out that white space? Thank you so much for your assistance. Have a nice day!

    • Hi Joe,

      The issue here is that you have CSS style rules for the too generic .post class. These end up being applied to all elements with the class post on the page. This happens to include breadcrumbs representing posts (of any type).

      Also, I noticed you are using the deprecated <center> HTML tag. I strongly encourage you to move to a more modern way to center elements using CSS.

      -John Havlik

  7. Having trouble styling the breadcrumb links. Haven’t done CSS in a long time. I inspected the element and saw links are in a div class of breadcrumbs, with the breadcrumbs having classes of “home” “taxonomy” and “category”. I came up with:

    div.breadcrumbs a.taxonomy.category:link { color: #00ff00; }
    div.breadcrumbs a.taxonomy.category:visited { color: #00ff00; }
    div.breadcrumbs a.taxonomy.category:hover { color: #70DB93; }
    div.breadcrumbs a.taxonomy.category:active { color: #70DB93; }

    Nothing is working – tried a few different variations. Any ideas?

Leave a Reply

Your email address will not be published. Required fields are marked *