Documentation

Hook Reference

Breadcrumb NavXT is extend-able via provided actions and filters. These hooks are outlined below. You may also find the Breadcrumb NavXT entry on hookr.io useful.

Action Reference

Beginning with Breadcrumb NavXT 3.5, actions were introduced to enhance extensibility of the plugin. If you prefer the WordPress action API over using OOP principles for plugin extension these are what you are looking for. The currently available actions are:

bcn_widget_display_types

This action hook is run within the select form element tags for the ‘Output Trail As:’ setting in the widget. This action complements the bcn_widget_display_trail action. The current widget instance options array is passed into the hooked function. This action was introduced in version 5.3. It receives one parameter:

  • $instance – (array)(required) The settings for the particular instance of the widget

bcn_widget_display_trail

This action hook will run if the widget display type is not one of the built in types (e.g. added via the bcn_widget_display_types action). It is located near the end of bcn_widget::widget(). The current widget instance options array is passed into the hooked function. This action was introduced in version 5.3. It receives one parameter:

  • $instance – (array)(required) The settings for the particular instance of the widget

bcn_after_fill

This action hook will run just after the trail has been populated. It is located in bcn_breadcrumb_trail::fill(). It receives one parameter:

  • &$breadcrumb_trail – (bcn_breadcrumb)(required) A reference to the current bcn_breadcrumb_trail instance.

Note: Do not exit with a cleared bcn_breadcrumb_trail::trail, otherwise an inescapable loop may result.

Related Articles

bcn_before_fill

This action hook will run just after the trail population check, and before attempting to fill bcn_breadcrumb_trail::trail. It is located in bcn_breadcrumb_trail::fill(). It receives one parameter:

  • &$breadcrumb_trail – (bcn_breadcrumb_trail)(required) A reference to the current bcn_breadcrumb_trail instance.

Note: Do not exit with a cleared bcn_breadcrumb_trail::trail, otherwise an inescapable loop may result.

Filter Reference

Beginning with Breadcrumb NavXT 4.0, some filters have been introduced to simplify the modification of some of Breadcrumb NavXT’s behaviors. The currently available filters are:

bcn_display_separator

This filter is applied within the bcn_breadcrumb_trail class in the display_loop() function just before assembling the breadcrumb string. This filter was introduced in version 7.2. It receives four parameters:

  • $separator – (string)(required) The separator to place after the current breadcrumb.
  • $position – (integer)(optional) The current breadcrumb position at the current depth in the breadcrumb trail
  • $last_position – (integer)(optional) The last possible position at this depth of the breadcrumb trail (size of the breadcrumb trail at this depth)
  • $depth – (integer)(optional) The current depth (dimension/level) within the breadcrumb trail

Related Articles

bcn_before_loop

This filter is applied within the bcn_breadcrumb_trail class in the display_loop() function at the beginning of the function. This filter was introduced in version 7.1. It receives one parameter:

  • $breadcrumbs – (array)(required) The array of bcn_breadcrumb objects that comprise the breadcrumb trail.

bcn_opts_update_to_save

This filter is applied within the mtekk\adminKit\adminKit class in the opts_update() function just before saving the settings to the option entry. This filter was introduced in version 7.0. It receives one parameter:

  • $settings_diff – (array)(required) The array of non-default valued mtekk\adminKit\setting objects which will be saved to the option entry.

bcn_breadcrumb_linked

This filter is applied within the bcn_breadcrumb class in the set_linked member function before setting the internal $linked property. This filter was introduced in 6.5. It receives three parameters:

  • $linked– (bool)(required) Whether or not the breadcrumb is linked
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

Related Articles

bcn_show_type_term_archive

This filter is applied within the breadcrumb_navxt_trail class in the type_archive() function. This filter was introduced in version 6.4. It receives two parameters:

  • $display – (boolean)(required) Whether or not to add the post type (filterable via bcn_type_archive_post_type) archive breadcrumb to the breadcrumb trail for term archives
  • $taxonomy – (string)(optional) The name of the taxonomy for term archive the breadcrumb trail is being generated for

bcn_show_post_private

This filter is applied within the bcn_breadcrumb_trail class in the post_parents() and do_post()functions. This filter is intended to allow users to override the default behavior of Breadcrumb NavXT to include private posts in the breadcrumb trail of their published children. This filter was introduced in version 6.4. It receives two parameters:

  • $display – (boolean)(required) Whether or not the post specified in the second parameter is to be included in the breadcrumb trail
  • $ID – (integer)(optional) The ID of the post in question

Related Articles

bcn_display_attribute_array

This filter is applied within the bcn_breadcrumb_trail class in the display_loop() function. This filter was introduced in version 6.3 to be an easier to use version of bcn_display_attributes. It receives three parameters:

  • $attribute_array – (array)(required) A key-value pair array of the attributes placed in the li tag that wraps the each breadcrumb. Keys are attribute names, values is an array of values for the attribute
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

bcn_register_rest_endpoint

This filter is applied within the bcn_rest_controller class in the register_rest_route() function. This filter was introduced in version 6.2. It receives four parameters:

  • $register_rest_endpoint – (boolean)(required) The boolean decision whether or not to allow the REST endpoint to be registered
  • $endpoint – (string)(optional) The name of the REST API endpoint being registered
  • $version – (string)(optional) The REST API version of the endpoint being registered
  • $methods – (array)(optional) The array of methods for the REST API endpoint being registered

Related Articles

bcn_breadcrumb_assembled_json_ld_array

This filter is applied within the bcn_breadcrumb class in the assemble_json_ld() function. This filter was introduced in version 6.2 with three parameters. It receives three parameters:

  • $json_ld_array – (array)(required) The JSON-LD array that will be returned by bcn_breadcrumb::assemble_json_ld() to filter
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

bcn_display_attributes

This filter is applied within the bcn_breadcrumb_trail class in the display_loop() function. This filter was introduced in version 6.0 to replace the deprecated bcn_li_attributes. It receives three parameters:

  • $li_attributes – (string)(required) The attributes placed in the li tag that wraps the each breadcrumb
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

Related Articles

bcn_default_hierarchy_display

This filter is applied within the breadcrumb_navxt class in the find_posttypes() function. It provides a method to override the default hierarchy display choice for custom post types. This filter was introduced in version 6.0. It receives three parameters:

  • $default_hierarchy_display – (boolean)(required) The default choice to either display or not display a hierarchy for the custom post type
  • $post_type – (string)(optional) The name of the post type that the default hierarchy type applies to
  • $hierarchy_type – (string)(optional) The hierarchy type (BCN_DATE, BCN_POST_PARENT, or a valid taxonomy name) that Breadcrumb NavXT is going to use as the default for the custom post type

bcn_default_hierarchy_type

This filter is applied within the breadcrumb_navxt class in the find_posttypes() function. It provides a method to override the default hierarchy type for custom post types. This filter was introduced in version 6.0. It receives two parameters:

  • $hierarchy_type – (string)(required) The hierarchy type (BCN_DATE, BCN_POST_PARENT, or a valid taxonomy name) that Breadcrumb NavXT is going to use as the default for the custom post type
  • $post_type – (string)(optional) The name of the post type that the default hierarchy type applies to

bcn_add_post_type_arg

This filter is applied within the breadcrumb_navxt_trail class in the maybe_add_post_type_arg() function. This filter was introduced in version 5.4. It receives three parameters:

  • $add_query_arg – (boolean)(required) The boolean decision whether or not to add the post type query argument to the URL to filter
  • $type – (string)(optional) The name of the post type that is under consideration for addition to the URL
  • $taxonomy – (string|NULL)(optional) The taxonomy name for the archive in question (may be null)

Related Articles

bcn_pick_post_term

This filter is applied within the bcn_breadcrumb_trail class in the post_hierarchy() function. This filter was introduced in version 5.4 with three parameters. In version 5.5 a fourth parameter was added. It receives four parameters:

  • $term – (WP_Term|boolean)(required) The term object returned by bcn_breadcrumb_trail::pick_post_terms() to filter (note that this parameter may be the boolean value false)
  • $id – (id)(optional) The ID of the post this term is for
  • $type – (string)(optional) The post type name for the post represented by the ID in the second parameter
  • $taxonomy – (string)(optional) The name of the taxonomy the term belongs to

bcn_post_terms

This filter is applied within the breadcrumb_navxt_trail class in the post_terms() function. This filter was introduced in version 5.4. It receives three parameters:

  • $terms – (array)(required) The array of term objects returned by get_the_terms() to filter
  • $taxonomy – (string)(optional) The name of the taxonomy for the terms
  • $id – (int)(optional) The ID of the post the terms are for

Related Articles

bcn_type_archive_post_type

This filter is applied within the breadcrumb_navxt_trail class in the type_archive() function. This filter was introduced in version 5.2. It receives one parameter:

  • $post_type – (string)(required) The name of the post type to use for the post type archive breadcrumb

bcn_settings_init

This filter is applied within the breadcrumb_navxt class in the wp_loaded() function. This filter was introduced in version 5.0. In 7.0, this filter was moved to the setup_setting_defaults() function and the array passed into the filter is now a settings (compliant with the mtekk/adminKit/setting interface) array instead of opts array. It receives one parameter:

  • $settings – (array)(required) The settings array for Breadcrumb NavXT

bcn_li_attributes

This filter is applied within the bcn_breadcrumb_trail class in the display_list() function. This filter was introduced in version 5.0. This filter was deprecated in version 6.0, use the new bcn_display_attributes filter instead. It receives three parameters:

  • $li_attributes – (string)(required) The attributes placed in the li tag that wraps the each breadcrumb
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

bcn_breadcrumb_trail_object

This filter is applied before instantiating the breadcrumb_navxt class. This filter is intended to allow users to extend the bcn_breadcrumb_trail class and still use the existing admin interfaces. This filter was introduced in version 5.0. It receives one parameter:

  • $breadcrumb_trail – (bcn_breadcrumb_trail)(required) The instance of bcn_breadcrumb_trail that breadcrumb_navxt class will use

bcn_show_cpt_private

This filter is applied within the bcn_admin class in the admin_page() function. This filter is intended to allow users to override the default behavior of Breadcrumb NavXT to hide settings for non-public post types. This filter was introduced in version 4.3. It receives two parameters:

  • $public – (boolean)(required) Whether or not the post type is a publicly visible post type as represented by the public property of the post type object
  • $name – (string)(optional) The name of the post type

bcn_show_tax_private

This filter is applied within the bcn_admin class in the admin_page() function. This filter is intended to allow users to override the default behavior of Breadcrumb NavXT to hide settings for non-public taxonomies. This filter was introduced in version 4.3. In version 6.0, a third parameter was added. It receives three parameters:

  • $public – (boolean)(required) Whether or not the taxonomy is a publicly visible taxonomy as represented by the public property of the taxonomy object
  • $taxonomy_name – (string)(optional) The name of the taxonomy
  • $posttype_name – (string)(optional) The name of the post type that the taxonomy is available for, may be NULL if a post type is not available

bcn_template_tags

This filter is applied within the bcn_breadcrumb class in the assemble() function. This filter was introduced in version 4.4. It receives three parameters:

  • $replacements – (array)(required) The array of template tags and replacements. This array contains key value pairs, where a key is the template tag, and the corresponding value is the value to replace the tag with
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

Related Articles

bcn_allowed_html

This filter is applied within the bcn_admin (by means of the mtekk_adminkit::wp_loaded()) and the bcn_breadcrumb class in the class constructor. Note that Breadcrumb NavXT itself registers a filter for this filter to load in extended attributes for select tags, it is advised that end users use a priority with value greater than 1 to prevent unexpected results. This filter was introduced in version 4.4. It receives one parameter:

  • $allowed_html – (array)(required) The array result of acceptable HTML tags and attributes. See the WordPress codex for wp_kses() for an example of this array structure

Related Articles

bcn_breadcrumb_types

This filter is applied within the bcn_breadcrumb class in the assemble() function. This filter was introduced in version 5.0. It receives two parameters:

  • $type – (array)(required) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

bcn_breadcrumb_template

This filter is applied within the bcn_breadcrumb class in the set_template member function before passing into wp_kses() and then setting the internal $template property. This filter was introduced in 4.4. It receives three parameters:

  • $template – (string)(required) The template that is being set for the breadcrumb
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

bcn_breadcrumb_url

This filter is applied within the bcn_breadcrumb class in the set_url member function before passing into esc_url() and then setting the internal $url property. This filter was introduced in 4.3. In 4.4 two additional parameters were made available. It receives three parameters:

  • $url – (string)(required) The URL that is being set for the breadcrumb
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

Related Articles

bcn_breadcrumb_title

This filter is applied within the bcn_breadcrumb class in the set_title member function before setting the internal $title property. In 4.2 the title string passed to filtering functions is accompanied by the internal type array to provide context. In 4.4 the third parameter was added. It receives three parameters:

  • $title – (string)(required) The title that is being set for the breadcrumb
  • $type – (array)(optional) The array of type strings for the breadcrumb
  • $id – (int|NULL)(optional) The ID of the resource represented by the breadcrumb, will be NULL if no suitable ID exists

Related Articles

Pages: 1 2 3 4
Modified by on

435 thoughts on “Documentation”

  1. 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! :)

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

  3. How can I hide main category in woocommerce product page and leave just subcategory? And can I do all links active?

    • 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?

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

  8. 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?

  9. Hey there, Does anyone know how to display the full title with all the pages.

    For instead of Home > Accounting I want

    Home > Accounting > Buisness accounting services > industry >child care

  10. Hello,
    in my website, only for some pages i need to add a custom word in the breadcrumb trail, between Home > and the current page.
    How can i do it?
    Thank you for your help
    Simone

  11. Hi there,

    many thanks for this plugin. I do have one issue though.
    I build my pages with the Divi builder tool, and I need to have the breadcrumb displayed beneath some elements of my page.

    I know there is no shortcode to do this within the breadcrumb plugin.
    I tried to create one on my own, but the breadcrumb is displayed at the top of the page, out of the divi builder itself. Most of time this is due to an echo rather than a return in the display function, but if I check the bcn_display function, it is supposed to be a return.

    Do you know if there is a way to display the breadcrumb at a certain position of my page?

    Many thanks in advance.

  12. I am using the widget on my Posts and wanted to use it in my shop for products. However, it appears that does not work. Is it a known limitation? Is there a tweak to make it work?

    • Hi James,

      My initial thought is that this is likely due to your theme having a different widget sidebar for the products page (if that is the case, you will need to setup the widget on that sidebar as well). However, this is only if the breadcrumb trail/widget is not showing up at all on the product pages (could test this by using the Title field in the widget and see if only that shows up). If that is not the case, then it may be a conflict with how the product pages are setup (I’d need more information to further diagnose the issue).

      -John Havlik

  13. How do I set “home page” for taxonomies? I can see a dropdown for custom post types, but what I need to manually set the page for taxonomies as well.

    • In WordPress, there isn’t a concept of a home/root page for taxonomies. Taxonomies only get a home/root page that is inferred from the post type they are associated with. If you are trying to map an hierarchical taxonomy term to a page, you may find Breadcrumb NavXT Paths helpful.

      -John Havlik

  14. In 6.2.0 NavXT REST API endpoints are no longer enabled by default. Can you tell me how to enable them, because my WP/react project now lost its breadcrumb functionality. Thanks in advance, regards, Mark

  15. Hi, I cant add the “home” on the breadcrump. It put only the things after the home… Can you help me please ?

    • Can you elaborate as to the problem you are having? Breadcrumb NavXT will by default try to generate the home breadcrumb, though it may use the site title rather than ‘home’. This can be changed by replacing %htitle% and %title% with home in the home breadcrumb templates in the Breadcrumb NavXT settings page. If it is not displaying and “display the home breadcrumb” is checked in the settings page, please check to ensure the breadcrumb is not being hidden by CSS (use your web browser’s builtin inspector tool to see what markup Breadcrumb NavXT is generating, looking for the home breadcrumb).

      -John Havlik

Comments are closed.