README

一款基本的WordPress插件，提供扩展的高级功能。为主题和插件开发者提供了一种简单的方式来实现高度可定制的面包屑功能，特别适用于他们的需求。

管理与设置

尽管此插件提供了多种扩展方式，但即使没有编程技能的人也可以使用。

如果Carbon Breadcrumbs作为WordPress插件安装并激活，则会在WordPress管理中的“设置”中显示“Carbon Breadcrumbs”页面。此页面允许修改默认渲染设置以适应首选设置。以下是一些可用的设置

• 粘合剂 - 在面包屑项之间显示。
• 链接之前 - 在面包屑项链接之前显示。
• 链接之后 - 在面包屑项链接之后显示。
• 包装之前 - 在显示面包屑项之前显示。
• 包装之后 - 在显示面包屑项之后显示。
• 标题之前 - 在面包屑项标题之前显示。
• 标题之后 - 在面包屑项标题之后显示。
• 最小项数 - 确定显示面包屑路径所需的最小项数。
• 最后一个项链接 - 是否将最后一个面包屑项作为链接。
• 显示首页项？ - 是否显示首页面包屑项。
• 首页项标题 - 确定首页项的标题。
• 渲染器 - 确定渲染器对象的类名。

如果此插件手动包含在主题中，则默认情况下不会显示管理设置页面。这允许主题开发者根据需要禁用对面包屑路径设置的控件。在这种情况下，可以通过定义CARBON_BREADCRUMB_ENABLE_ADMIN常量并将其设置为true来启用管理设置。为此，请将以下行添加到您的主题functions.php文件中

define('CARBON_BREADCRUMB_ENABLE_ADMIN', true);

注意：通过使用carbon_breadcrumbs_renderer_default_options过滤器，管理设置会覆盖默认面包屑设置。这意味着开发人员仍然可以通过使用carbon_breadcrumbs_before_render动作来覆盖这些设置。以下readme中详细说明了carbon_breadcrumbs_renderer_default_options和carbon_breadcrumbs_before_render。

使用与示例

基本

以下示例是显示面包屑路径的最基本方式，使用默认选项。

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

简单配置选项

以下示例将显示具有指定设置的面包屑路径。

<?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',
));
?>

中级

以下示例将创建并渲染面包屑路径，同时为您提供选项来自定义配置。您可以使用内置方法进一步操作路径对象。

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

高级

以下示例将创建、设置和渲染一个自定义面包屑项的面包屑路径，并使用自定义渲染器。它还利用了一些可用的过滤器和操作。代码的每个部分都可以单独使用，以便在需要对路径进行高级操作时使用。以下是在示例中可以看到的：自定义渲染器设置、向特定项前添加文本、向某些项的URL后添加内容、添加自定义项、添加页面项及其祖先、通过名称和链接删除特定项、通过优先级删除所有项、初始化设置和渲染。代码的每个部分都相应地进行了注释，以便您了解其功能。

<?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();
?>

注意：Carbon_Breadcrumb_Trail 项保存在一个多维数组中，其中数组键包含优先级，值是包含该优先级所有项的数组，按添加日期排序（从旧到新）。

配置选项

以下选项可以传递给 Carbon_Breadcrumb_Trail()、Carbon_Breadcrumb_Trail::output() 或 Carbon_Breadcrumb_Trail_Renderer() - 您正在使用的选项。

glue

(字符串)。默认：' > '.

显示在面包屑项之间的HTML。

link_before

(字符串)。默认：''（无）.

显示在每个面包屑项的 <a> 链接之前的HTML。

link_after

(字符串)。默认：''（无）.

显示在每个面包屑项的 <a> 链接之后的HTML。

wrapper_before

(字符串)。默认：''（无）.

显示在所有面包屑项之前的HTML。

wrapper_after

(字符串)。默认：''（无）.

显示在所有面包屑项之后的HTML。

title_before

(字符串)。默认：''（无）.

显示在面包屑项标题之前的HTML。

title_after

(字符串)。默认：''（无）.

显示在面包屑项标题之后的HTML。

min_items

(整数)。默认：2.

显示路径所需的最小面包屑项数量。

last_item_link

(布尔值)。默认：true.

最后一个项是否为链接。

display_home_item

(布尔值)。默认：true.

是否显示 首页 面包屑项。

home_item_title

(字符串)。默认：首页.

首页项的标题。

renderer

(字符串)。默认：Carbon_Breadcrumb_Trail_Renderer.

用于面包屑路径渲染器对象的类名。应与声明的PHP类对应。此设置用于 Carbon_Breadcrumb_Trail 实例，而不是传递给 Carbon_Breadcrumb_Trail_Renderer 实例。

操作 & 过滤器

以下操作和过滤器可以允许开发人员修改默认行为，并在各种情况下添加自定义功能。

过滤器

the_title

$title (字符串)。未过滤的项标题。

此过滤器是WordPress的默认过滤器，用于所有帖子、术语和用户面包屑项的标题。

carbon_breadcrumbs_renderer_class

$class_name (字符串)。渲染器类的名称。

此过滤器允许您修改用于渲染面包屑路径的默认渲染器类。

carbon_breadcrumbs_renderer_default_options

$options (数组)。所有默认选项的列表。

此过滤器允许您修改面包屑渲染器的默认选项。如果未指定其他设置，则使用这些选项。以下列出了所有默认选项及其默认值：

$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 (布尔值)。是否在渲染前自动排序项。

此过滤器允许您指定是否在渲染前自动按优先级排序项。

carbon_breadcrumbs_item

$item (Carbon_Breadcrumb_Item)。面包屑项对象。

此过滤器允许您在渲染前修改面包屑项。

carbon_breadcrumbs_item_link

$link (字符串). 面包屑项的链接。

$item (Carbon_Breadcrumb_Item)。面包屑项对象。

此过滤器允许您在渲染之前修改面包屑项的链接 URL。

carbon_breadcrumbs_item_title

$title (字符串). 面包屑项的标题。

$item (Carbon_Breadcrumb_Item)。面包屑项对象。

此过滤器允许您在渲染之前修改面包屑项的标题。

carbon_breadcrumbs_item_attributes

$attributes (数组). 面包屑项的自定义属性。

$item (Carbon_Breadcrumb_Item)。面包屑项对象。

$trail (Carbon_Breadcrumb_Trail). 面包屑路径对象。

$trail_renderer (Carbon_Breadcrumb_Trail_Renderer). 面包屑路径渲染对象。

$counter (整数). 此面包屑项的索引。

此过滤器允许您在渲染之前修改面包屑项的链接属性。默认情况下，会添加 target="_self" 属性。此数组期望将属性名称作为数组元素的键，将属性值作为数组元素的值。示例： 'target' => '_blank'。

carbon_breadcrumbs_item_output

$output (字符串). 面包屑项的 HTML 输出。

$item (Carbon_Breadcrumb_Item)。面包屑项对象。

$trail (Carbon_Breadcrumb_Trail). 面包屑路径对象。

$trail_renderer (Carbon_Breadcrumb_Trail_Renderer). 面包屑路径渲染对象。

$index (整数). 此面包屑项的索引。

此过滤器允许您在渲染之后修改面包屑项的 HTML 输出。

carbon_breadcrumb_enable_admin

$enabled (布尔值). 是否启用管理界面。

此过滤器允许您手动启用/禁用管理界面。当您启用/禁用管理界面时，也会启用/禁用显示面包屑路径时的管理员设置。

操作

carbon_breadcrumbs_before_setup_trail

$trail (Carbon_Breadcrumb_Trail). 面包屑路径对象。

此动作允许您在设置（添加面包屑项）开始之前修改面包屑路径对象。

carbon_breadcrumbs_after_setup_trail

$trail (Carbon_Breadcrumb_Trail). 面包屑路径对象。

此动作允许您在设置（添加面包屑项）完成后修改面包屑路径对象。

carbon_breadcrumbs_before_render

$trail (Carbon_Breadcrumb_Trail). 面包屑路径对象。

此动作允许您在面包屑路径渲染之前修改面包屑路径对象。