Download the PHP package tyxla/carbon-breadcrumbs without Composer

Carbon Breadcrumbs

A basic WordPress plugin for breadcrumbs with advanced capabilities for extending. Provides the theme and plugin developers an easy way to build and implement highly customizable breadcrumb functionality, specifically tailored to their needs.

Administration & Settings

Although this plugin provides various ways to be extended, it can be used by people with no programming skills.

If Carbon Breadcrumbs is installed and activated as a WordPress plugin, a Carbon Breadcrumbs page will appear in Settings in the WordPress administration. This page allows the default rendering settings to be modified to the preferred ones. The following settings are available:

• Glue - Displayed between the breadcrumb items.
• Link Before - Displayed before the breadcrumb item link.
• Link After - Displayed after the breadcrumb item link.
• Wrapper Before - Displayed before displaying the breadcrumb items.
• Wrapper After - Displayed after displaying the breadcrumb items.
• Title Before - Displayed before the breadcrumb item title.
• Title After - Displayed after the breadcrumb item title.
• Min Items - Determines the minimum number of items, required to display the breadcrumb trail.
• Last Item Link - Whether the last breadcrumb item should be a link.
• Display Home Item? - Whether the home breadcrumb item should be displayed.
• Home Item Title - Determines the title of the home item.
• Renderer - Determines the class name of the renderer object.

If this plugin is manually included in a theme, the administration settings page will not be shown by default. This allows theme developers to disable control over the breadcrumb trail settings, if necessary. In this case, the administration settings can still be enabled by defining the CARBON_BREADCRUMB_ENABLE_ADMIN constant and setting it to true. To do that, add the following line to your theme functions.php file:

define('CARBON_BREADCRUMB_ENABLE_ADMIN', true);

Note: The administration settings override the default breadcrumb settings, by using the carbon_breadcrumbs_renderer_default_options filter. This means that developers can still override these settings by using the carbon_breadcrumbs_before_render action. Both carbon_breadcrumbs_renderer_default_options and carbon_breadcrumbs_before_render are documented below in this readme.

Usage & Examples

Basic

The following example is the most basic way to display a breadcrumb trail, using the default options.

Simple with configuration options

The following example will display a breadcrumb trail with the specified settings.

Intermediate

The following example will create and render an breadcrumb trail, providing you the option to set it up yourself with your preferred configuration. You can further manipulate the trail object by using its built-in methods.

Advanced

The following example will create, setup and render a breadcrumb trail with a custom breadcrumb items and will use a custom renderer. It also takes advantage of some of the available filters and actions. Each portion of the code can be used separately in case you need to perform advanced manipulation on the trail. The following can be seen in the example: custom renderer setup, prepending text to specific items, appending something to the URLs of some items, adding a custom item, adding a page item along with its ancenstry, removing a certain item by name and link, removing all items by priority, initialization with setup and rendering. Each portion of the code is commented accordingly so you can understand what it does.

Note: The Carbon_Breadcrumb_Trail items are preserved in a multidimensional array, where the array keys contain the priority, and the value is an array with all items of that priority, ordered by the date of their addition (oldest to newest).

Configuration Options

The following options can be passed to Carbon_Breadcrumb_Trail(), Carbon_Breadcrumb_Trail::output() or Carbon_Breadcrumb_Trail_Renderer() - whichever you are using.

glue

(string). Default: ' > '.

The HTML, displayed between the breadcrumb items.

link_before

(string). Default: '' (none).

The HTML before the <a> link of each of the breadcrumb items.

link_after

(string). Default: '' (none).

The HTML after the <a> link of each of the breadcrumb items.

wrapper_before

(string). Default: '' (none).

The HTML before all breadcrumb items.

wrapper_after

(string). Default: '' (none).

The HTML after all breadcrumb items.

title_before

(string). Default: '' (none).

The HTML displayed before the breadcrumb item title.

title_after

(string). Default: '' (none).

The HTML displayed after the breadcrumb item title.

min_items

(int). Default: 2.

The minimum number of breadcrumb items, required to display the trail.

last_item_link

(bool). Default: true.

Whether the last item will be a link or not.

display_home_item

(bool). Default: true.

Whether the Home breadcrumb item should be displayed or not.

home_item_title

(string). Default: Home.

The title of the home item.

renderer

(string). Default: Carbon_Breadcrumb_Trail_Renderer.

The class name that will be used for the breadcrumb trail renderer object. Should correspond to a declared PHP class. This setting is used in the Carbon_Breadcrumb_Trail instance instead of being passed to the Carbon_Breadcrumb_Trail_Renderer instance.

Actions & Filters

The following actions and filters can allow developers to modify the default behavior and hook to add custom functionality in various situations.

Filters

the_title

$title (string). The unfiltered title of the item.

This filter is default for WordPress and is applied on the titles of all Post, Term and User breadcrumb items.

carbon_breadcrumbs_renderer_class

$class_name (string). The name of the renderer class.

This filter can allow you to modify the default renderer class, which is used for rendering the breadcrumb trail.

carbon_breadcrumbs_renderer_default_options

$options (array). A list of all default options.

This filter allows you to modify the default options of the breadcrumb renderer. They are used if no other settings are specified. Here is a list of all default options and their default values:

$default_options = array(
    'glue' => ' > ',
    'link_before' => '',
    'link_after' => '',
    'wrapper_before' => '',
    'wrapper_after' => '',
    'title_before' => '',
    'title_after' => '',
    'min_items' => 2,
    'last_item_link' => true,
    'display_home_item' => true,
    'home_item_title' => __('Home', 'carbon_breadcrumbs'),
    'renderer' => 'Carbon_Breadcrumb_Trail_Renderer',
);

carbon_breadcrumbs_auto_sort_items

$autosort (bool). Whether to autosort the items before rendering or not.

This filter allows you to specify whether to automatically sort the items by their priority right before they are rendered.

carbon_breadcrumbs_item

$item (Carbon_Breadcrumb_Item). The breadcrumb item object.

This filter allows you to modify a breadcrumb item right before its rendering.

carbon_breadcrumbs_item_link

$link (string). The link of the breadcrumb item.

$item (Carbon_Breadcrumb_Item). The breadcrumb item object.

This filter allows you to modify the link URL of a breadcrumb item right before its rendering.

carbon_breadcrumbs_item_title

$title (string). The title of the breadcrumb item.

$item (Carbon_Breadcrumb_Item). The breadcrumb item object.

This filter allows you to modify the title of a breadcrumb item right before its rendering.

carbon_breadcrumbs_item_attributes

$attributes (array). The custom attributes of the breadcrumb item.

$item (Carbon_Breadcrumb_Item). The breadcrumb item object.

$trail (Carbon_Breadcrumb_Trail). The breadcrumb trail object.

$trail_renderer (Carbon_Breadcrumb_Trail_Renderer). The breadcrumb trail renderer object.

$counter (int). The index of this breadcrumb item.

This filter allows you to modify the link attributes of a breadcrumb item right before its rendering. By default, the target="_self" attribute is added. This array expects the attribute name as the array element key, and the attribute value as the array element value. Example: 'target' => '_blank'.

carbon_breadcrumbs_item_output

$output (string). The HTML output of the breadcrumb item.

$item (Carbon_Breadcrumb_Item). The breadcrumb item object.

$trail (Carbon_Breadcrumb_Trail). The breadcrumb trail object.

$trail_renderer (Carbon_Breadcrumb_Trail_Renderer). The breadcrumb trail renderer object.

$index (int). The index of this breadcrumb item.

This filter allows you to modify the HTML output of a breadcrumb item right after its rendering.

carbon_breadcrumb_enable_admin

$enabled (bool). Whether to enable the administration interface.

This filter allows you to enable/disable manually the administration interface. When you enable/disable the administration interface, you also enable/disable the admin settings when displaying the breadcrumb trail.

Actions

carbon_breadcrumbs_before_setup_trail

$trail (Carbon_Breadcrumb_Trail). The breadcrumb trail object.

This action allows you to modify the breadcrumb trail object before the setup (which adds breadcrumb items) has started.

carbon_breadcrumbs_after_setup_trail

$trail (Carbon_Breadcrumb_Trail). The breadcrumb trail object.

This action allows you to modify the breadcrumb trail object after the setup (which adds breadcrumb items) has been completed.

carbon_breadcrumbs_before_render

$trail (Carbon_Breadcrumb_Trail). The breadcrumb trail object.

This action allows you to modify the breadcrumb trail object right before the breadcrumb trail rendering.