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_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 breadcrumb_navxt_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 breadcrumb_navxt_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

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. It receives one parameter:

  • $opts(array)(required) The options 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. 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 not 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. It receives two parameters:

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

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 not 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 not 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 not 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 not 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 not suitable ID exists

on

426 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

Leave a Reply

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