Kama и Jackky4 месяца назад103

Kama Breadcrumbs

Плагин создает цепочку ссылок от главной до текущей просматриваемой страницы. Такую цепочку принято называть «хлебные крошки».

Это новая версия — более простой, стабильный, расширяемый и понятный код. Измененная система хуков. Дополнительный функционал. Прошлый код значительно доработан.

Оглавление:

Вывод крошек в теме (Использование)

Используйте следующий код в файле темы, там где нужно вывести крошки.

<?php do_action( 'echo_kama_breadcrumbs' ) ?>

Или можно вызвать с передачей параметров:

<?php
$args = [
	'sep'             => ' › ',
	'on_front_page'   => false,
	'show_post_title' => false,
	//'markup'          => 'Microdata', // RDFa, Microdata, data-vocabulary.org
	//'priority_tax'    => [ 'category' ],
	//'number_tax'      => [ 'category' => 2 ],
	//'disable_tax'     => [ 'post_tags' ],
];

$l10n = [
	'tag' => 'Метка: <b>%s</b>',
];

do_action( 'echo_kama_breadcrumbs', $args, $l10n );
?>

Когда нужно получить HTML крошек (не выводить на экран), используйте код:

$breadcrumbs = kama_breadcrumbs( $args, $l10n );

// теперь выводим там где нужно
echo $breadcrumbs;

Параметры $args

Настройки вывода крошек указываются в виде массива, в параметре $args. Возможные элементы массива:

sep(строка)
Разделитель. Можно указать вместе с HTML оберткой: <span> » </span>.
По умолчанию: ' » '
on_front_page(true/false)
Выводить крошки на главной странице.
По умолчанию: true
show_post_title(true/false)
Показывать ли название записи в конце (последний элемент). Для записей, страниц, вложений.
По умолчанию: true
show_term_title(true/false)
Показывать ли название элемента таксономии в конце (последний элемент). Для меток, рубрик и других такс.
По умолчанию: true
last_sep(true/false)
показывать последний разделитель, когда заголовок в конце не отображается.
По умолчанию: true
nofollow(true/false)
Добавлять rel=nofollow к ссылкам?
По умолчанию: false
wrap_class(строка)
CSS класс для главного div.
По умолчанию: 'kama_breadcrumbs'
link_class(строка)
CSS класс для элемента крошек a.
По умолчанию: 'kb_link'
title_class(строка)
CSS класс заголовка элемента.
По умолчанию: 'kb_title'
sep_class(строка)
CSS класс разделителя.
По умолчанию: 'kb_sep'
priority_tax(массив)

Приоритетные таксономии, нужно когда запись находится в нескольких таксономиях: array( 'category', 'tax_name' ).
Порядок имеет значение — чем раньше тем важнее.

В значениях можно указать приоритетные элементы таксономий, тогда название таксономии нужно указывать в ключе.

Когда запись находится в нескольких элементах одной таксы одновременно. Например:

array(
	'category' => [ 45, 'term_name', 'имя терма' ],
	'tax_name' => [ 1, 2, 'name' ]
)

В этом коде category - это название таксономии для которой указываются приоритетные элементы.

  • 45 - ID термина
  • term_name - ярлык

  • имя терма - заголовок.

    Порядок 45, term_name и имя терма имеет значение: чем раньше тем важнее. Все указанные термины важнее неуказанных.

По умолчанию: array()

disable_tax
Таксономии которые нужно исключить из показа в крошках: array( 'post_tag', 'tax_name' )
По умолчанию: array()
number_tax

Позволяет выводить в крошках для записей сразу несколько таксономий.

Например, если указать [ 'post' => 2 ], то для типа записи post выведет крошки для двух таксономий по умолчанию: category и post_tag.

Поменять порядок можно в параметре priority_tax.
По умолчанию: array()

markup(string/array)

Микроразметка. Может быть:

Можно указать свой массив разметки, например:

'markup' => [
	'wrappatt'  => '<div class="kama_breadcrumbs">%s</div>',
	'linkpatt'  => '<a href="%s">%s</a>',
	'titlepatt' => '<span class="kb_title">%s</span>',
	'seppatt'   => '<span class="kb_sep">%s</span>'
],

По умолчанию: 'Microdata'

JSON_LD(true/false)
Следует ли добавлять микроразметку JSON-LD в HTML.
По умолчанию: true
use_the_title_filter(true/false)
Использовать ли фильтр the_title для заголовков записей.
По умолчанию: false

Параметры $l10n

Параметры строк (локализации) указываются в параметре $l10n в виде массива. Значения по умолчанию:

// Локализация
$l10n = array(
	'home'       => 'Главная',
	'paged'      => 'Страница %d',
	'_404'       => 'Ошибка 404',
	'search'     => 'Результаты поиска по запросу - <b>%s</b>',
	'author'     => 'Архив автора: <b>%s</b>',
	'year'       => 'Архив за <b>%d</b> год',
	'month'      => 'Архив за: <b>%s</b>',
	'day'        => 'Архив за <b>%1$s число</b>, %2$s', // Архив за 5 число, среда
	'attachment' => 'Медиа: %s',
	'tag'        => 'Записи по метке: <b>%s</b>',
	'tax_tag'    => '%1$s из "%2$s" по тегу: <b>%3$s</b>',
	// tax_tag выведет: 'тип_записи из "название_таксы" по тегу: имя_термина'.
	// Если нужны отдельные холдеры, например только имя термина, пишем так: 'записи по тегу: %3$s'
);

Строки переводятся на англ. если у сайта выбран англ. язык.

Фильтры (хуки)

Все хуки плагина. Ниже показан код как хук определяется в плагине:

// Позволяет отключить вывод крошек
if( apply_filters( 'disable_kama_breadcrumbs', null ) ) return;
// фильтрует строки локализации - $l10n - это массив
$l10n = apply_filters( 'kama_breadcrumbs_l10n', $l10n );
// фильтрует параметры - $args - это массив
$args = apply_filters( 'kama_breadcrumbs_args', $args );
// вывод: все виды записей с терминами, или термины
$term = apply_filters( 'kama_breadcrumbs_term', $term );
// возможность изменить элементы крошек
/**
 * Allows change breadcrumbs elements.
 *
 * @param Kama_Breadcrumbs_Elem[] $elms  Multidimensional associative array of breadcrumbs elements.
 * @param Kama_Breadcrumbs        $this  Object of current class.
 * @param WP_Post_Type|null       $ptype Post Type object. Null when post type for the current query is not detected.
 */
$elms = apply_filters( 'kama_breadcrumbs_filter_elements', $elms, $this, $this->ptype );
// возможность изменить элементы крошек,
// после того, как все элементы были собраны в одномерный (плоский) массив
/**
 * Allows change breadcrumbs elements after it's all elements where
 * collected in the flat array.
 *
 * @param Kama_Breadcrumbs_Elem[] $elms  Associative array of elements.
 * @param Kama_Breadcrumbs        $this  Object of current class.
 * @param WP_Post_Type|null       $ptype Post Type object. Null when post type for the current query is not detected.
 */
$flat_elms = apply_filters( 'kama_breadcrumbs_filter_flat_elements', $flat_elms, $this, $ptype );
// фильтрует готовый HTML код крошек
return apply_filters( 'kama_breadcrumbs', sprintf( $arg->wrappatt, $out ), $arg->sep, $loc, $arg );

Примеры использования хуков

Изменение параметров по умолчанию

// установим параметры по умолчанию
add_filter( 'kama_breadcrumbs_args', 'my_kama_breadcrumbs_args' );

function my_kama_breadcrumbs_args( $args ){

	$my_args = [
		'sep'             => ' › ', // ▸
		'on_front_page'   => 1,
		'show_post_title' => 0,
		//'show_term_title' => 0,
		//'last_sep'      => 0,
		'markup'          =>'RDFa',
		// или своя маркировка
		'markup' => [
			'wrappatt'  => '<div class="kama_breadcrumbs">%s</div>',
			'linkpatt'  => '<li><a href="%s">%s</a></li>',
			'titlepatt' => '<li class="active">%s</li>',
			'seppatt'   => '<span class="kb_sep">%s</span>',
		],
		'priority_tax' => [ 'category', 'tplcat', 'wpfunccat' ],
	];

	return $my_args + $args;
}

Локализация (строки перевода)

// изменим строки перевода
add_filter( 'kama_breadcrumbs_l10n', 'my_kama_breadcrumbs_l10n' );

function my_kama_breadcrumbs_l10n( $l10n ){

	$my_l10n = [
		'home'    => '<i style="display:none;">Главная</i><span class="dashicons dashicons-admin-home"></span>',
		'tax_tag' => 'По метке: <b>%3$s</b>',
	];

	return $my_l10n + $l10n;
}

Чтобы изменить имеющие УРЛ в крошках или добавить свои крошки нужно использовать фильтр kama_breadcrumbs_filter_elements.

Функция прикрепленная к этому фильтру получает массив и должна вернуть измененный массив. Этот массив - это и есть крошки, только в виде многомерного массива, он потом превратиться в HTML код крошек.

Для изменения или создания элементов крошек используются два метода (они автоматически создают указанную в параметре markup микроразметку):

// для любого элемента крошек (кроме последнего)
$class->makelink( $url, $title )

// для последнего элемента крошек (ссылка будет выводится, только если нужна)
$class->maketitle( $url, $title )

Код нужно вставлять в файл темы functions.php или куда-либо еще, главное до того как будут выведены крошки.

#1 Пример изменения элементов крошек

Чтобы все было понятно пройдусь по шагам.

Все изменения с крошками делаются через фильтр kama_breadcrumbs_filter_elements. Для начала посмотрим что лежит в крошках, чтобы понимать какие ключи массива есть:

add_filter( 'kama_breadcrumbs_filter_elements', 'kama_breadcrumbs_filter_elms', 11, 3 );

function kama_breadcrumbs_filter_elms( $elms, $class, $ptype ){
	die( print_r( $elms ) );
}

В результате вы увидите такой массив (если мы на странице поста):

Array
(
	[home] => Array (
		[0] => Kama_Breadcrumbs_Elem Object ( ... )
	)

	[home_after] => Array( )

	[single] => Array (
		[category__tax_crumbs] => Array (
			[0] => Kama_Breadcrumbs_Elem Object( ... )

			[1] => Kama_Breadcrumbs_Elem Object( ... )
		)

	)
)

Как видим тут 3 крошки: home > category > category (орриентируйтесь по ключам массива - они не меняются и зависят от типа данных к которым относится конкретная крошка).

Теперь, например, нам нужно изменить ссылку на главную, для этого меняем крошку которая находится в ключе home:

add_filter( 'kama_breadcrumbs_filter_elements', function( $elms, $class, $ptype ){

	$elms['home'] = $class->makelink( 'https://site.com/path', 'Title' );

	return $elms; // не забываем вернуть

}, 11, 3 );

Или можно добавить еще одну крошку после ссылки на главную, для этого закидываем еще один элемент в массив с ключом home:

add_filter( 'kama_breadcrumbs_filter_elements', function( $elms, $class, $ptype ){

	$elms['home'][] = $class->makelink( 'https://site.com/path', 'Title' );

	return $elms; // не забываем вернуть

}, 11, 3 );

По такой системе можно удалять/изменять/добавлять крошки как угодно.

Важно отметить, что массив понимает любой уровень вложенности. Например, можно написать так и все будет работать:

add_filter( 'kama_breadcrumbs_filter_elements', function( $elms, $class, $ptype ){

	$elms['home'][] = [
		'foo' => [
			$class->makelink( 'https://site.com/path', 'Title' )
		]
	];

	return $elms; // не забываем вернуть

}, 11, 3 );

#2 Добавим элементы крошек после ссылки на главную

// добавить свои ссылки в крошки
add_filter( 'kama_breadcrumbs_filter_elements', 'breadcrumbs_add_elements', 10, 3 );

function breadcrumbs_add_elements( $elms, $class, $ptype ){
	global $post;

	// смотрим какие элементы есть в массиве и добавляем куда и что нужно
	// print_r( $elms );

	// запись находится в рубрике mycat
	if( is_single() && has_category( 'mycat', $post ) ){

		// добавим 2 ссылки (2 элемента) после главной
		$elms['home'][] = [
			$class->makelink( '/inventory', 'Инвентарь' ),
			$class->makelink( '/other', 'Другое' )
		];
	}

	return $elms;
}

#3 Пример для woocommerce

add_filter( 'kama_breadcrumbs_filter_elements', 'kama_breadcrumbs_add_elements', 10, 3 );

function kama_breadcrumbs_add_elements( $elms, $class, $ptype ){

	if ( is_woocommerce() ) {

		$page = get_post( wc_get_page_id( 'shop' ) );

		if ( is_shop() && ! is_paged() ) {
			$elms['home_after'] = $class->maketitle( get_the_permalink( $page ), get_the_title( $page ) );
		}
		else {
			$elms['home_after'] = $class->makelink( get_permalink( $page ), get_the_title( $page ) );
		}
	}

	return $elms;
}

#4 Варианты добавить «крошку» после главной

add_filter( 'kama_breadcrumbs_filter_elements', 'kama_breadcrumbs_add_elements', 10, 3 );

function kama_breadcrumbs_add_elements( $elms, $class, $ptype ){

	// можно так:
	$elms['home_after'][] = $class->makelink( 'http://example.com/functions', 'Функции' );

	// или сотрем имеющиеся элементы и добавим свой:
	$elms['home_after'] = $class->makelink( 'http://example.com/functions', 'Функции' );

	// или добавим сразу несколько ссылок:
	$elms['home_after'][] = [
		$class->makelink('http://example.com/functions', 'Функции' ),
		$class->makelink('http://example.com/hooks', 'Хуки' ),
	];

	// или заменим на сразу несколько своих ссылок (удалим текущее значение home_after):
	$elms['home_after'] = [
		$class->makelink('http://example.com/functions', 'Функции' ),
		$class->makelink('http://example.com/hooks', 'Хуки' ),
	];

	return $elms;
}

Массив $elms

Как выглядит массив $elms передаваемый в хук (элементы будут отличаться на разных страницах сайта):

Array(

	[home] =>   <span property="itemListElement" typeof="ListItem">
					<a href="http://example.com" property="item" typeof="WebPage"><span property="name"><i style="display:none;">Главная</i><span class="dashicons dashicons-admin-home"></span></span></a>
					<meta property="position" content="ORDERNUM" />
				</span>

	[home_after] => Array(
			[0] =>  <span property="itemListElement" typeof="ListItem">
						<a href="/functions" property="item" typeof="WebPage"><span property="name">Функции</span></a>
						<meta property="position" content="ORDERNUM" />
					</span>
			[1] =>  <span property="itemListElement" typeof="ListItem">
						<a href="/functions/template_tags" property="item" typeof="WebPage"><span property="name">Теги шаблона</span></a>
						<meta property="position" content="ORDERNUM" />
					</span>
	)

	[single] => Array(
			[wpfunccat__tax_crumbs] => Array(
					[0] =>  <span property="itemListElement" typeof="ListItem">
								<a href="http://example.com/function-cat/miscellaneous" property="item" typeof="WebPage"><span property="name">Прочие функции</span></a>
								<meta property="position" content="ORDERNUM" />
							</span>
					[1] =>  <span property="itemListElement" typeof="ListItem">
								<a href="http://example.com/function-cat/zaschita-bloga" property="item" typeof="WebPage"><span property="name">Защита</span></a>
								<meta property="position" content="ORDERNUM" />
							</span>
			)

			[title] =>  <span class="kb_title" property="itemListElement" typeof="ListItem">
								<span property="name">form_option</span>
								<meta property="position" content="ORDERNUM">
							</span>
	)

)

В этот массив можно добавлять свои элементы. В значении может быть строка или вложенный массив. В результате все значения этого многомерного массива будут собраны и выведены в крошках по порядку.

Названия ключей массива $elms. Например, home_after, нужны, чтобы проще было «сунуть» свою ссылку в нужное место, на работу кода они не влияют. Т.е. при добавлении своих элементов, ключ массива можно указать любой или вообще не указывать.

Получение массива крошек (не HTML код)

С версии 4.22 было добавлено два метода, чтобы можно было получить массив данных крошек, без вывода HTML кода на экран.

$args = [];
$breadcrumbs = new Kama_Breadcrumbs( $args );

print_r(  $breadcrumbs->get_crumbs_flat_elements()  );
// или
print_r(  $breadcrumbs->get_crumbs_elements()  );

Удаление элементов из крошек

Когда нужно удалить существующие элементы, так же как и при добавлении используем фильтр kama_breadcrumbs_filter_elements.

Так, чтобы например удалить ссылку Главная, нужно удалить элемент массива, точнее очистить его:

// изменяем крошки
add_filter( 'kama_breadcrumbs_filter_elements', 'breadcrumbs_change_elements', 10, 3 );

function breadcrumbs_change_elements( $elms, $class, $ptype ){
  global $post;

  // смотрим какие элементы есть в массиве и добавляем куда и что нужно
  // print_r( $elms );

  // удалим ссылку на главную (очистим элемент home там лежит элемент "главная")
  $elms['home'] = [];

  return $elms;
}

Отключить крошки (по условию)

Допустим нам нужно отключить вывод хлебных крошек на странице /profile. Сделать это можно через фильтр disable_kama_breadcrumbs:

add_filter( 'disable_kama_breadcrumbs', function(){
	return is_page('profile');
} );

Или если крошки у вас выводятся через хук echo_kama_breadcrumbs, то можно просто убрать все прикрепленные к нему функции:

add_action( 'wp', function(){

	if( is_page('profile') ){
		remove_all_filters( 'echo_kama_breadcrumbs' );
	}
} );

Изменение классов под БЭМ верстку

## параметры по умолчанию — kama_breadcrumbs
add_filter( 'kama_breadcrumbs_args', function( $args )
{
	$base       = isset($args['bem']['base'])   ? $args['bem']['base']  : 'breadcrumbs';
	$mods       = isset($args['bem']['mods'])   ? $args['bem']['mods']  : [];

	$inner      = $base . '__inner';
	$item       = $base . '__item';
	$title      = $base . '__title';
	$link       = $base . '__link';
	$sep        = $base . '__sep';

	$base_mod   = isset($mods['base'])          ? ' ' . $base . '--' . $mods['base']    : '';
	$inner_mod  = isset($mods['inner'])         ? ' ' . $inner . '--' . $mods['inner']  : '';
	$item_mod   = isset($mods['item'])          ? ' ' . $item . '--' . $mods['item']    : '';
	$title_mod  = isset($mods['title'])         ? ' ' . $title . '--' . $mods['title']  : '';
	$link_mod   = isset($mods['link'])          ? ' ' . $link . '--' . $mods['link']    : '';
	$sep_mod    = isset($mods['sep'])           ? ' ' . $sep . '--' . $mods['sep']      : '';

	return array_merge( $args, [
		'sep'           => ' — ',
		'sep_class'     => $sep . $sep_mod,

		// своя разметка
		'markup'    =>
		[
			'wrappatt'  => '
				<div class="' . $base . $base_mod . '" itemscope itemtype="https://schema.org/BreadcrumbList">
					<div class="' . $inner . $inner_mod . '">%s</div>
				</div>',

			'linkpatt'  => '
				<span class="' . $item . $item_mod . '" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
					<a href="%s" class="' . $link . $link_mod . '">%s</a>
					<meta itemprop="item" content="PERMALINK" />
					<meta itemprop="name" content="NAME" />
					<meta itemprop="position" content="ORDERNUM" />
				</span>',

			'titlepatt' => '
				<span class="' . $title . $title_mod . '" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
					%s
					<meta itemprop="item" content="PERMALINK" />
					<meta itemprop="name" content="NAME" />
					<meta itemprop="position" content="ORDERNUM" />
				</span>
			',
		],
	] );
} );

## пример использования в шаблоне:

$bc_args = [
	'bem'   => [
		'mods'  => [
			'inner'     => 'grey_class',
			'link'      => 'red_color',
		],
	]
];

echo kama_breadcrumbs( $bc_args );

/**
 * Выведет:
 * - у враппера class="breadcrumbs__inner breadcrumbs__inner--grey_class"
 * - у ссылок class="breadcrumbs__link breadcrumbs__link--red_color"
 */

Еще примеры

Смотрите в вопросе.

До этого из: mast have (обязательный)
103 комментария
Полезные - 9 Все