README

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.

<?php Carbon_Breadcrumb_Trail::output(); ?>

Simple with configuration options

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

<?php
Carbon_Breadcrumb_Trail::output(array(
	'glue' => ' &gt; ', // glue between breadcrumb items
	'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',
));
?>

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.

<?php
$trail = new Carbon_Breadcrumb_Trail(array(
	'glue' => ' &gt; ',
	'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',
));
$trail->setup(); // setup the trail by generating necessary breadcrumb items
$trail->render(); // display the breadcrumb trail
?>

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.

<?php
# A custom breadcrumb trail renderer class
class Crb_Carbon_Breadcrumb_Trail_Renderer extends Carbon_Breadcrumb_Trail_Renderer {
	// your custom renderer methods & overrides here
}

# Modify the default breadcrumb trail renderer class
function crb_carbon_breadcrumbs_renderer_class($renderer_class) {
	return 'Crb_Carbon_Breadcrumb_Trail_Renderer';
}

# Prepend "Blog Post: " to the title of the post items
add_filter('carbon_breadcrumbs_item_title', 'crb_carbon_breadcrumbs_item_title_post', 10, 2);
function crb_carbon_breadcrumbs_item_title_post($item_title, $item) {
	if ( is_a($item, 'Carbon_Breadcrumb_Item_Post') && $item->get_subtype() == 'post' ) {
		$item_title = 'Blog Post: ' . $item_title;
	}
	return $item_title;
}

# Append "?test=1" to the link of the post items
add_filter('carbon_breadcrumbs_item_link', 'crb_carbon_breadcrumbs_item_link_post', 10, 2);
function crb_carbon_breadcrumbs_item_link_post($item_link, $item) {
	if ( is_a($item, 'Carbon_Breadcrumb_Item_Post') && $item->get_subtype() == 'post' ) {
		$item_link = add_query_arg('test', 1, $item_link);
	}
	return $item_link;
}

# Add a new custom item by specifying title, link and priority
add_action('carbon_breadcrumbs_after_setup_trail', 'crb_add_custom_item');
function crb_add_custom_item($trail) {
	$trail->add_custom_item('Link Title', 'http://example.com/custom/link/', 500);
}

# Add a new page item and its ancestry
add_action('carbon_breadcrumbs_after_setup_trail', 'crb_add_test_page_item');
function crb_add_test_page_item($trail) {
	$locator = Carbon_Breadcrumb_Locator::factory('post', 'page');
	$priority = 500;
	$page_id = 123;
	$items = $locator->get_items($priority, $page_id);
	if ($items) {
		$trail->add_item($items);
	}
}

# Remove the "Electronics" category item
add_action('carbon_breadcrumbs_after_setup_trail', 'crb_remove_electronics_category_item', 500);
function crb_remove_electronics_category_item($trail) {
	$trail->remove_item('Electronics', 'http://example.com/category/electronics/');
}

# Remove all items with priority 999
add_action('carbon_breadcrumbs_after_setup_trail', 'crb_remove_items_priority_999', 500);
function crb_remove_items_priority_999($trail) {
	$trail->remove_item_by_priority(999);
}

# Initialize the trail as bulleted list
$trail = new Carbon_Breadcrumb_Trail(array(
	'glue' => '',
	'link_before' => '<li>',
	'link_after' => '</li>',
	'wrapper_before' => '<ul>',
	'wrapper_after' => '</ul>',
	'title_before' => '',
	'title_after' => '',
	'min_items' => 1,
	'last_item_link' => true,
	'display_home_item' => true,
	'home_item_title' => __('Home', 'carbon_breadcrumbs'),
	'renderer' => 'Carbon_Breadcrumb_Trail_Renderer',
));

# Setup the trail by generating necessary breadcrumb items
$trail->setup();

# Display the breadcrumb trail
$trail->render();
?>

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.